trmnl_preview 0.8.9 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04ad9007c6a3cc5b8d3c724ec349b204c977f861fc41cb637428fba48c715b89
-  data.tar.gz: ebc4873c90c6effcfc356ff13e38eb9b63d7547af14b85dc62eb84bb48145893
+  metadata.gz: cbbc567f2937e7dd1aabc75991df616728f88fa858d797384a4a63453265be5c
+  data.tar.gz: 1b1e543aa9ea1dddbb456f061f1538c22cc0edd849fc6faced3d67fa5f682677
 SHA512:
-  metadata.gz: c43c02691942bcea76563ce97d2b7e55f3327d207747a930374f750ad4edd257f8ed5b5edb94424ec008c3d0047735df33cb51399d44023a28522169613c6148
-  data.tar.gz: 125935ffec1af3606b4a1f6e0d7687137349f25f2da0da1f03e989ad598c25b34cf56f23964ab5d16f448632307b858744bd3d7547c5babda94bb8e1bb828ba7
+  metadata.gz: 7b0ab9feab22239ce5e2eaa6c9b2fc7d1f889927e267c14d83eb6ec02e60a973acb9194fee59cae709ea7640c43741186788588b33e9d76ac023a5d5f09280d4
+  data.tar.gz: c18a319c45dec945b5c8f71d56c47f4478b8a82bceaed429b475cce4f57cb8a29541bcf7b1312e8fb9624513aebbd434d05c6e64f02d32322e9628cffc08553f

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 
 # Changelog
 
+## 0.9.0
+
+- Added OAuth2 support for local plugin preview (beta). Configure a provider with the flat `oauth_*` keys in `src/settings.yml` (authorize and token URLs, scopes, optional PKCE), which round-trip through `trmnlp push` and `pull`. Set `TRMNL_OAUTH_CLIENT_ID` and `TRMNL_OAUTH_CLIENT_SECRET` in your environment (credentials stay local and are never synced), and register `http://localhost:4567/oauth/callback` as the redirect URI in your OAuth app. `trmnlp serve` shows a Connect banner that runs the authorization code flow in the browser, stores the tokens in the cache directory (never in the project), and refreshes them before they expire. The access token is exposed to polling templates as `{{ oauth_access_token }}`, matching the hosted service. This is a beta feature; please report incorrect behaviour at https://github.com/usetrmnl/trmnlp/issues.
+
+## 0.8.10
+
+- Fixed Python serverless transforms failing on Windows. The local subprocess backend hardcoded `python3`, which the python.org Windows installer does not put on PATH (it installs `python` and the `py` launcher), so every Python transform raised "interpreter not available". The interpreter is now resolved from a per-language list of command candidates (`python3`, then `python`, then the `py` launcher) using a cross-platform PATH lookup, leaving POSIX behavior unchanged. (#116)
+
 ## 0.8.9
 
 - Fixed `trmnlp serve` binding to localhost under Podman, which left the dev server unreachable through published ports. Container detection only looked for `/.dockerenv`, which Docker writes but Podman does not, so `serve` fell back to `127.0.0.1`. It now also checks for `/run/.containerenv`, which Podman writes, so the automatic `0.0.0.0` bind works for both runtimes. (#112)

data/README.md

@@ -314,6 +314,63 @@ variables:
 
 ```
 
+## OAuth2
+
+This feature is in beta. Please report incorrect behaviour at https://github.com/usetrmnl/trmnlp/issues.
+
+Some private plugins fetch data from a third-party API that requires the user to authorize access first (the OAuth2 authorization code flow). `trmnlp` can run that flow locally so you can preview the plugin with a real token. It injects the token into your polling request the same way the hosted service does, so a plugin that works locally behaves the same once deployed.
+
+### 1. Configure the provider
+
+Add the flat `oauth_*` keys to `src/settings.yml`. These are the provider definition, and they round-trip through `trmnlp push` and `pull` (the hosted service stores them on the plugin setting):
+
+```yaml
+oauth_enabled: "true"
+oauth_authorize_url: https://github.com/login/oauth/authorize
+oauth_token_url: https://github.com/login/oauth/access_token
+oauth_scopes: "read:user user:email"
+oauth_pkce_enabled: "true"      # optional, default false
+# oauth_scope_separator: " "      # optional; some providers use ","
+# oauth_refresh_url: https://...  # optional; defaults to oauth_token_url
+```
+
+Your OAuth app credentials stay local and are never synced, so set them in your environment:
+
+```sh
+export TRMNL_OAUTH_CLIENT_ID=your-oauth-app-client-id
+export TRMNL_OAUTH_CLIENT_SECRET=your-oauth-app-client-secret
+```
+
+PKCE-only providers do not need a client secret.
+
+### 2. Register the redirect URI
+
+In your OAuth app on the provider's site, register this redirect URI:
+
+```
+http://localhost:4567/oauth/callback
+```
+
+Match the port if you run `trmnlp serve` on a different one.
+
+### 3. Connect
+
+Run `trmnlp serve` and open the preview. When OAuth is configured but not yet connected, a **Connect account** banner appears. Click it to authorize in your browser. `trmnlp` stores the tokens in its cache directory (never in your project) and refreshes them automatically before they expire. Use the **Disconnect** link to reconnect after changing scopes.
+
+### 4. Use the token
+
+Reference the token in your `src/settings.yml` polling configuration with the same variables the hosted service exposes:
+
+- `{{ oauth_access_token }}`
+- `{{ oauth_token_type }}` (defaults to `Bearer`)
+- `{{ oauth_client_id }}`
+
+For example, as a polling header:
+
+```
+Authorization=Bearer {{ oauth_access_token }}
+```
+
 ## Serverless Transforms
 
 `trmnlp` can run a transform script (`python`, `ruby`, `php`, or `node`) against the polled API response before handing data to your Liquid templates — matching the hosted plugin service's behavior.

data/lib/trmnlp/app.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'securerandom'
 require 'sinatra'
 require 'sinatra/base'
 
@@ -33,6 +34,10 @@ module TRMNLP
       def h(text)
         Rack::Utils.escape_html(text.to_s)
       end
+
+      # Derived from the live request so it matches at authorize and exchange
+      # time; this is the single URI the developer registers with the provider.
+      def oauth_callback_uri = "#{request.base_url}/oauth/callback"
     end
 
     def initialize(*args)
@@ -44,6 +49,10 @@ module TRMNLP
       @user_data_assembler = @context.user_data_assembler
       @transform_pipeline = @context.transform_pipeline
       @watcher = @context.watcher
+      @oauth_session = @context.oauth_session
+      # Keyed by state. A shared hash (built once) survives Sinatra's
+      # per-request dup, like @live_reload_clients below.
+      @oauth_state = {}
       @screenshot = Screenshot.new(pool: settings.browser_pool)
 
       @poller.poll_data
@@ -118,6 +127,35 @@ module TRMNLP
       redirect back
     end
 
+    get '/oauth/connect' do
+      halt 400, 'OAuth is not configured. Add the oauth_* keys to src/settings.yml.' unless @oauth_session.configured?
+
+      state = SecureRandom.hex(16)
+      if @oauth_session.pkce?
+        verifier = OAuth::Pkce.verifier
+        challenge = OAuth::Pkce.challenge(verifier)
+      end
+      @oauth_state[state] = verifier
+      redirect @oauth_session.authorize_url(redirect_uri: oauth_callback_uri, state:, code_challenge: challenge)
+    end
+
+    get '/oauth/callback' do
+      halt 400, "OAuth provider returned an error: #{params[:error]}" if params[:error]
+      halt 400, 'OAuth state mismatch. Restart at /oauth/connect.' unless @oauth_state.key?(params[:state])
+
+      verifier = @oauth_state.delete(params[:state])
+      @oauth_session.complete(code: params[:code], redirect_uri: oauth_callback_uri, code_verifier: verifier)
+      @poller.poll_data
+      redirect '/'
+    rescue StandardError => e
+      halt 502, "OAuth token exchange failed: #{e.message}"
+    end
+
+    get '/oauth/disconnect' do
+      @oauth_session.disconnect
+      redirect '/'
+    end
+
     Screen.all.each do |screen|
       view = screen.name
       get "/#{view}" do

data/lib/trmnlp/config/plugin.rb

@@ -30,14 +30,14 @@ module TRMNLP
       def webhook? = strategy == 'webhook'
       def static? = strategy == 'static'
 
-      def polling_urls
+      def polling_urls(extra_variables: {})
         # allow project-level config to override
         urls = project_config.user_data_overrides.dig('trmnl', 'plugin_settings',
                                                       'polling_url') || @config['polling_url']
 
         return [] if urls.nil?
 
-        with_custom_fields(urls).strip.split("\n")
+        with_custom_fields(urls, extra_variables:).strip.split("\n")
       end
 
       # for {{ trmnl }}
@@ -45,18 +45,18 @@ module TRMNLP
 
       def polling_verb = @config['polling_verb'] || 'GET'
 
-      def polling_headers
+      def polling_headers(extra_variables: {})
         # NOTE: render Liquid across the full headers string first so {% if %} blocks
         # spanning multiple key=value pairs are preserved. Splitting on
         # '&' or '=' before rendering would shatter tags into multiple values.
-        rendered = with_custom_fields(@config['polling_headers'] || '')
+        rendered = with_custom_fields(@config['polling_headers'] || '', extra_variables:)
         string_to_hash(rendered)
       end
 
       # for {{ trmnl }}
       def polling_headers_encoded = polling_headers.map { |k, v| "#{k}=#{v}" }.join('&')
 
-      def polling_body = with_custom_fields(@config['polling_body'] || '')
+      def polling_body(extra_variables: {}) = with_custom_fields(@config['polling_body'] || '', extra_variables:)
 
       def dark_mode = @config['dark_mode'] || 'no'
 
@@ -107,7 +107,9 @@ module TRMNLP
 
       attr_reader :paths, :project_config
 
-      def with_custom_fields(value) = project_config.with_custom_fields(value)
+      def with_custom_fields(value, extra_variables: {})
+        project_config.with_custom_fields(value, extra_variables:)
+      end
 
       def string_to_hash(str, delimiter: '=')
         str.split('&').map do |k_v|

data/lib/trmnlp/config/project.rb

@@ -38,10 +38,11 @@ module TRMNLP
 
       def user_data_overrides = @config['variables'] || {}
 
-      # for interpolating custom_fields into polling_* options
-      def with_custom_fields(value)
+      # extra_variables lets the poller inject live values (e.g.
+      # oauth_access_token) into the same custom-field render.
+      def with_custom_fields(value, extra_variables: {})
         custom_fields_with_env = custom_fields.transform_values { |v| with_env(v) }
-        parse_liquid(value).render(custom_fields_with_env)
+        parse_liquid(value).render(custom_fields_with_env.merge(extra_variables))
       end
 
       def time_zone = @config['time_zone'] || 'UTC'

data/lib/trmnlp/context.rb

@@ -22,7 +22,17 @@ module TRMNLP
     # Context is the composition root: it wires and memoizes the runtime
     # object graph. Callers take the collaborator they need and talk to it
     # directly — Context does not forward methods on their behalf.
-    def poller = @poller ||= Poller.new(config:, paths:, reporter:)
+    def poller = @poller ||= Poller.new(config:, paths:, oauth_session:, reporter:)
+
+    def oauth_session
+      @oauth_session ||= begin
+        provider = OAuth::Provider.new(config.plugin.settings)
+        OAuth::Session.new(provider:,
+                           token_store: OAuth::TokenStore.new(paths.oauth_tokens),
+                           client: OAuth::Client.new(provider))
+      end
+    end
+
     def transform_pipeline = @transform_pipeline ||= TransformPipeline.new(config:, paths:, reporter:)
     def user_data_assembler = @user_data_assembler ||= UserDataAssembler.new(config:, paths:, transform_pipeline:)
     def renderer = @renderer ||= Renderer.new(config:, paths:, user_data_assembler:)

data/lib/trmnlp/oauth/client.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'oauth2'
+require 'uri'
+
+module TRMNLP
+  module OAuth
+    class Client
+      def initialize(provider)
+        @provider = provider
+      end
+
+      def authorize_url(redirect_uri:, state:, code_challenge: nil)
+        params = { redirect_uri:, scope: provider.scopes, state: }
+        params.merge!(code_challenge:, code_challenge_method: 'S256') if code_challenge
+        oauth_client(provider.token_url).auth_code.authorize_url(**params)
+      end
+
+      def exchange_code(code:, redirect_uri:, code_verifier: nil)
+        params = { redirect_uri: }
+        params[:code_verifier] = code_verifier if code_verifier
+        bundle oauth_client(provider.token_url).auth_code.get_token(code, params)
+      end
+
+      def refresh(refresh_token:)
+        client = oauth_client(provider.refresh_url)
+        bundle OAuth2::AccessToken.new(client, nil, refresh_token:).refresh!
+      end
+
+      private
+
+      attr_reader :provider
+
+      def oauth_client(token_url)
+        OAuth2::Client.new(
+          provider.client_id, provider.client_secret,
+          site: origin(token_url), authorize_url: provider.authorize_url,
+          token_url:, auth_scheme:
+        )
+      end
+
+      # A PKCE public client has no secret, so its client_id must travel in the
+      # request body; a confidential client authenticates with HTTP Basic.
+      def auth_scheme = provider.client_secret ? :basic_auth : :request_body
+
+      # oauth2 posts tokens through a connection built from the site, so give it
+      # the endpoint's origin even though the full URL is absolute.
+      def origin(url)
+        uri = URI(url)
+        port = uri.port == uri.default_port ? nil : ":#{uri.port}"
+        "#{uri.scheme}://#{uri.host}#{port}"
+      end
+
+      def bundle(token)
+        TokenBundle.new(
+          access_token: token.token,
+          refresh_token: token.refresh_token,
+          expires_at: token.expires_at,
+          token_type: token.params['token_type'] || 'Bearer'
+        )
+      end
+    end
+  end
+end

data/lib/trmnlp/oauth/pkce.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'digest'
+require 'base64'
+
+module TRMNLP
+  module OAuth
+    # Proof Key for Code Exchange (RFC 7636, S256).
+    module Pkce
+      module_function
+
+      def verifier = SecureRandom.urlsafe_base64(64)
+
+      def challenge(verifier)
+        Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+      end
+    end
+  end
+end

data/lib/trmnlp/oauth/provider.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module OAuth
+    # Provider definition from the flat oauth_* keys in src/settings.yml (which
+    # round-trip through push/pull). Credentials stay local and env-first so
+    # they are never synced or committed.
+    class Provider
+      ENV_CLIENT_ID = 'TRMNL_OAUTH_CLIENT_ID'
+      ENV_CLIENT_SECRET = 'TRMNL_OAUTH_CLIENT_SECRET'
+
+      def initialize(settings, env: ENV)
+        @settings = settings || {}
+        @env = env
+      end
+
+      def authorize_url = settings['oauth_authorize_url']
+      def token_url = settings['oauth_token_url']
+      def refresh_url = settings['oauth_refresh_url'] || token_url
+      def scopes = settings['oauth_scopes']
+      def scope_separator = settings['oauth_scope_separator'] || ' '
+      def pkce? = truthy?(settings['oauth_pkce_enabled'])
+      def enabled? = truthy?(settings['oauth_enabled'])
+      def client_id = env_first(ENV_CLIENT_ID, settings['oauth_client_id'])
+      def client_secret = env_first(ENV_CLIENT_SECRET, settings['oauth_client_secret'])
+
+      def configured?
+        return false unless enabled? && authorize_url && token_url && client_id
+
+        pkce? || present?(client_secret)
+      end
+
+      private
+
+      attr_reader :settings, :env
+
+      def truthy?(value) = [true, 'true'].include?(value)
+
+      def env_first(key, fallback)
+        value = env[key]
+        present?(value) ? value : fallback
+      end
+
+      def present?(value) = !value.nil? && !value.empty?
+    end
+  end
+end

data/lib/trmnlp/oauth/session.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module OAuth
+    class RefreshError < StandardError; end
+
+    class Session
+      def initialize(provider:, token_store:, client:)
+        @provider = provider
+        @token_store = token_store
+        @client = client
+      end
+
+      def configured? = provider.configured?
+
+      def pkce? = provider.pkce?
+
+      def connected?
+        return false unless configured?
+
+        stored = token_store.read
+        !stored.nil? && !stored.access_token.nil?
+      end
+
+      def access_token = current_bundle&.access_token
+
+      def liquid_variables
+        return {} unless connected?
+
+        bundle = current_bundle
+        {
+          'oauth_access_token' => bundle.access_token,
+          'oauth_token_type' => bundle.token_type,
+          'oauth_client_id' => provider.client_id
+        }
+      end
+
+      def authorize_url(redirect_uri:, state:, code_challenge: nil)
+        client.authorize_url(redirect_uri:, state:, code_challenge:)
+      end
+
+      def complete(code:, redirect_uri:, code_verifier: nil)
+        token_store.write(client.exchange_code(code:, redirect_uri:, code_verifier:))
+      end
+
+      def disconnect = token_store.clear
+
+      private
+
+      attr_reader :provider, :token_store, :client
+
+      # Returns the stored token, transparently refreshing and re-persisting it
+      # when it is near expiry. nil when nothing is connected yet.
+      def current_bundle
+        stored = token_store.read
+        return nil if stored.nil? || stored.access_token.nil?
+
+        stored.expired? ? refreshed(stored) : stored
+      end
+
+      def refreshed(stale)
+        token_store.write stale.merge_refresh(client.refresh(refresh_token: stale.refresh_token))
+      rescue StandardError => e
+        raise RefreshError, "OAuth token refresh failed: #{e.message}. Reconnect at /oauth/connect."
+      end
+    end
+  end
+end

data/lib/trmnlp/oauth/token_bundle.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module OAuth
+    TokenBundle = Data.define(:access_token, :refresh_token, :expires_at, :token_type) do
+      def self.from_h(hash)
+        new(
+          access_token: hash['access_token'],
+          refresh_token: hash['refresh_token'],
+          expires_at: hash['expires_at'],
+          token_type: hash['token_type'] || 'Bearer'
+        )
+      end
+
+      def expired?
+        return false unless expires_at
+
+        # Treat as expired 5 minutes early so a token never dies mid-request.
+        expires_at.to_i - 300 <= Time.now.to_i
+      end
+
+      # A refresh response often omits the rotated refresh_token (and sometimes
+      # other fields); the prior values remain valid, so carry them forward.
+      def merge_refresh(fresh)
+        with(
+          access_token: fresh.access_token,
+          refresh_token: fresh.refresh_token || refresh_token,
+          expires_at: fresh.expires_at || expires_at,
+          token_type: fresh.token_type || token_type
+        )
+      end
+    end
+  end
+end

data/lib/trmnlp/oauth/token_store.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module TRMNLP
+  module OAuth
+    class TokenStore
+      def initialize(path)
+        @path = path
+      end
+
+      def read
+        return nil unless path.exist?
+
+        TokenBundle.from_h(JSON.parse(path.read))
+      end
+
+      def write(bundle)
+        path.dirname.mkpath
+        path.write(JSON.generate(bundle.to_h))
+        path.chmod(0o600)
+        bundle
+      end
+
+      def clear
+        path.delete if path.exist?
+      end
+
+      private
+
+      attr_reader :path
+    end
+  end
+end

data/lib/trmnlp/oauth.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'oauth/pkce'
+require_relative 'oauth/provider'
+require_relative 'oauth/token_bundle'
+require_relative 'oauth/token_store'
+require_relative 'oauth/client'
+require_relative 'oauth/session'

data/lib/trmnlp/paths.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'digest'
 require 'xdg'
 
 module TRMNLP
@@ -45,6 +46,10 @@ module TRMNLP
 
     def user_data = cache_dir.join('data.json')
 
+    # OAuth tokens are keyed per project root so working on two OAuth plugins
+    # does not clobber a shared token file.
+    def oauth_tokens = cache_dir.join('oauth', "#{Digest::SHA256.hexdigest(root_dir.to_s)[0, 16]}.json")
+
     def render_template = Pathname.new(__dir__).join('..', '..', 'web', 'views', 'render_html.erb')
 
     def src_files = src_dir.glob('*').select(&:file?)

data/lib/trmnlp/poller.rb

@@ -8,9 +8,10 @@ require_relative 'reporter'
 
 module TRMNLP
   class Poller
-    def initialize(config:, paths:, reporter: Reporter.new)
+    def initialize(config:, paths:, oauth_session:, reporter: Reporter.new)
       @config = config
       @paths = paths
+      @oauth_session = oauth_session
       @reporter = reporter
     end
 
@@ -39,25 +40,33 @@ module TRMNLP
 
     private
 
-    attr_reader :config, :paths, :reporter
+    attr_reader :config, :paths, :oauth_session, :reporter
 
     def aggregate_responses
-      responses = config.plugin.polling_urls.map { |url| fetch_one(url) }
+      # Resolve once per poll (it refreshes as a side effect), then share across
+      # every URL, header, and body render.
+      oauth_variables = oauth_session.liquid_variables
+      urls = config.plugin.polling_urls(extra_variables: oauth_variables)
+      responses = urls.map { |url| fetch_one(url, oauth_variables) }
       return responses.first if responses.size == 1
 
       responses.each_with_index.with_object({}) { |(r, i), h| h["IDX_#{i}"] = r }
     end
 
-    def fetch_one(url)
+    def fetch_one(url, oauth_variables)
       verb = config.plugin.polling_verb.upcase
-      response = perform_request(url, verb)
+      response = perform_request(url, verb, oauth_variables)
       reporter.info("#{verb} #{url} — received #{response.body.length} bytes (#{response.status} status)")
       parse_response(response)
     end
 
-    def perform_request(url, verb)
-      conn = Faraday.new(url:, headers: config.plugin.polling_headers)
-      verb == 'POST' ? conn.post { |req| req.body = config.plugin.polling_body } : conn.get
+    def perform_request(url, verb, oauth_variables)
+      conn = Faraday.new(url:, headers: config.plugin.polling_headers(extra_variables: oauth_variables))
+      if verb == 'POST'
+        conn.post { |req| req.body = config.plugin.polling_body(extra_variables: oauth_variables) }
+      else
+        conn.get
+      end
     end
 
     def parse_response(response)

data/lib/trmnlp/transform_backend/subprocess.rb

@@ -4,6 +4,7 @@ require 'open3'
 require 'tmpdir'
 
 require_relative '../transform_client'
+require_relative 'which'
 require_relative 'wrapper'
 
 module TRMNLP
@@ -19,11 +20,16 @@ module TRMNLP
       # Seconds a TERM'd process is given to exit before escalating to KILL.
       GRACE_PERIOD = 0.1
 
+      # Candidate commands per language, highest priority first. Windows is
+      # why a language needs more than one: its python.org installer provides
+      # `python` and the `py` launcher but no `python3`. `py` ranks last yet
+      # is the surest Windows hit — it stays on PATH even when the installer's
+      # optional "Add to PATH" step is skipped.
       INTERPRETERS = {
-        'python' => { cmd: 'python3', ext: 'py' },
-        'ruby' => { cmd: 'ruby',    ext: 'rb' },
-        'node' => { cmd: 'node',    ext: 'js' },
-        'php' => { cmd: 'php', ext: 'php' }
+        'python' => { cmds: %w[python3 python py], ext: 'py' },
+        'ruby' => { cmds: %w[ruby],                ext: 'rb' },
+        'node' => { cmds: %w[node],                ext: 'js' },
+        'php' => { cmds: %w[php],                  ext: 'php' }
       }.freeze
 
       def execute(code:, language:, stdin: '', timeout_seconds: DEFAULT_TIMEOUT)
@@ -40,7 +46,7 @@ module TRMNLP
           output_path = File.join(dir, 'output.json')
           src_path = File.join(dir, "transform.#{spec[:ext]}")
           File.write(src_path, Wrapper.for(language, code, sink_for(language, output_path)))
-          run_process(spec[:cmd], src_path, stdin, timeout_seconds, output_path)
+          run_process(Which.resolve(spec[:cmds]), src_path, stdin, timeout_seconds, output_path)
         end
       rescue Errno::ENOENT, Errno::EACCES => e
         failure("interpreter not available: #{e.message}")

data/lib/trmnlp/transform_backend/which.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module TransformBackend
+    # Resolves a command to the interpreter actually present on PATH, so one
+    # transform runs unchanged on platforms that name an interpreter
+    # differently — most pressingly Windows, which ships no `python3`.
+    module Which
+      module_function
+
+      # Falls back to the first candidate when none resolve, leaving the
+      # caller to surface the usual "interpreter not available" ENOENT.
+      def resolve(candidates, path: ENV.fetch('PATH', ''), pathext: ENV.fetch('PATHEXT', ''))
+        candidates.find { |cmd| locate(cmd, path: path, pathext: pathext) } || candidates.first
+      end
+
+      # Windows marks executables by extension, enumerated in PATHEXT
+      # (.EXE/.BAT/...); POSIX leaves PATHEXT unset and relies on the exec bit.
+      def locate(cmd, path: ENV.fetch('PATH', ''), pathext: ENV.fetch('PATHEXT', ''))
+        suffixes = pathext.split(File::PATH_SEPARATOR)
+        suffixes = [''] if suffixes.empty?
+        path.split(File::PATH_SEPARATOR)
+            .product(suffixes)
+            .map { |dir, suffix| File.join(dir, "#{cmd}#{suffix}") }
+            .find { |candidate| File.file?(candidate) && File.executable?(candidate) }
+      end
+    end
+  end
+end

data/lib/trmnlp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TRMNLP
-  VERSION = '0.8.9'
+  VERSION = '0.9.0'
 end

data/lib/trmnlp.rb

@@ -6,6 +6,7 @@ require 'trmnl/liquid'
 Oj.mimic_JSON
 TRMNL::Liquid::RailsHelpers = Module.new unless defined?(TRMNL::Liquid::RailsHelpers)
 require_relative 'trmnlp/errors'
+require_relative 'trmnlp/oauth'
 require_relative 'trmnlp/config'
 require_relative 'trmnlp/context'
 require_relative 'trmnlp/screen'

data/trmnl_preview.gemspec

@@ -54,6 +54,9 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'mini_magick', '~> 5.3'
   spec.add_dependency 'selenium-webdriver', '~> 4.44'
 
+  # OAuth2 (local plugin preview auth flow)
+  spec.add_dependency 'oauth2', '~> 2.0'
+
   # Utilities
   spec.add_dependency 'cgi', '~> 0.5'
   spec.add_dependency 'faraday', '~> 2.1'

data/web/views/index.erb

@@ -60,6 +60,12 @@
             </div>
         </menu>
 
+        <% if @oauth_session&.connected? %>
+          <div class="oauth-banner" style="padding: 0.5em 0.75em; margin: 0.5em 0; background: #efe; border: 1px solid #3a3; border-radius: 4px; color: #060;">OAuth account connected (beta). <a href="/oauth/disconnect">Disconnect</a> · <a href="https://github.com/usetrmnl/trmnlp/issues" target="_blank" rel="noopener">Report an issue</a></div>
+        <% elsif @oauth_session&.configured? %>
+          <div class="oauth-banner" style="padding: 0.5em 0.75em; margin: 0.5em 0; background: #eef; border: 1px solid #66c; border-radius: 4px; color: #234;"><a href="/oauth/connect">Connect account</a> to authorize this plugin's OAuth requests. OAuth is in beta. <a href="https://github.com/usetrmnl/trmnlp/issues" target="_blank" rel="noopener">Report an issue</a>.</div>
+        <% end %>
+
         <% if @transform_error %>
           <div class="transform-error" style="padding: 0.5em 0.75em; margin: 0.5em 0; background: #fee; border: 1px solid #c33; border-radius: 4px; color: #900; font-family: monospace; white-space: pre-wrap;">Transform error: <%= h @transform_error %></div>
         <% end %>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.8.9
+  version: 0.9.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -107,6 +107,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.44'
+- !ruby/object:Gem::Dependency
+  name: oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: cgi
   requirement: !ruby/object:Gem::Requirement
@@ -304,6 +318,13 @@ files:
 - lib/trmnlp/lint/checks/title_length.rb
 - lib/trmnlp/lint/checks/waits_for_dom_load.rb
 - lib/trmnlp/lint/source.rb
+- lib/trmnlp/oauth.rb
+- lib/trmnlp/oauth/client.rb
+- lib/trmnlp/oauth/pkce.rb
+- lib/trmnlp/oauth/provider.rb
+- lib/trmnlp/oauth/session.rb
+- lib/trmnlp/oauth/token_bundle.rb
+- lib/trmnlp/oauth/token_store.rb
 - lib/trmnlp/paths.rb
 - lib/trmnlp/poller.rb
 - lib/trmnlp/renderer.rb
@@ -313,6 +334,7 @@ files:
 - lib/trmnlp/screenshot.rb
 - lib/trmnlp/transform_backend/http.rb
 - lib/trmnlp/transform_backend/subprocess.rb
+- lib/trmnlp/transform_backend/which.rb
 - lib/trmnlp/transform_backend/wrapper.rb
 - lib/trmnlp/transform_client.rb
 - lib/trmnlp/transform_pipeline.rb