trmnl_preview 0.7.2 → 0.8.0

data/db/data/framework_versions.yml

@@ -0,0 +1,72 @@
+# Mirrored from the TRMNL design-system source.
+# Refresh with `rake framework:sync` — do not edit manually.
+latest: 3.1.1
+versions:
+- number: 0.0.1
+  released_at: '2024-06-22'
+- number: 0.0.2
+  released_at: '2024-06-23'
+- number: 0.0.3
+  released_at: '2024-07-09'
+- number: 0.0.4
+  released_at: '2024-07-11'
+- number: 0.0.5
+  released_at: '2024-07-14'
+- number: 0.0.6
+  released_at: '2024-08-18'
+- number: 0.0.7
+  released_at: '2024-09-19'
+- number: 1.0.0
+  released_at: '2024-11-03'
+- number: 1.0.1
+  released_at: '2025-01-21'
+- number: 1.0.2
+  released_at: '2025-02-04'
+- number: 1.0.3
+  released_at: '2025-02-06'
+- number: 1.0.4
+  released_at: '2025-02-24'
+- number: 1.0.5
+  released_at: '2025-04-23'
+- number: 1.1.0
+  released_at: '2025-05-19'
+- number: 1.1.1
+  released_at: '2025-05-20'
+- number: 1.2.0
+  released_at: '2025-07-28'
+- number: 2.0.0
+  released_at: '2025-09-14'
+- number: 2.0.1
+  released_at: '2025-11-10'
+- number: 2.1.0
+  released_at: '2025-12-30'
+- number: 2.2.0
+  released_at: '2026-01-13'
+- number: 2.2.1
+  released_at: '2026-01-16'
+- number: 2.3.0
+  released_at: '2026-02-07'
+- number: 2.3.1
+  released_at: '2026-02-09'
+- number: 2.3.2
+  released_at: '2026-02-26'
+- number: 2.3.3
+  released_at: '2026-03-02'
+- number: 2.3.7
+  released_at: '2026-03-20'
+- number: 3.0.0
+  released_at: '2026-04-01'
+- number: 3.0.1
+  released_at: '2026-04-03'
+- number: 3.0.2
+  released_at: '2026-04-03'
+- number: 3.0.3
+  released_at: '2026-04-07'
+- number: 3.0.4
+  released_at: '2026-04-29'
+- number: 3.0.5
+  released_at: '2026-05-01'
+- number: 3.1.0
+  released_at: '2026-04-29'
+- number: 3.1.1
+  released_at: '2026-05-01'

data/lib/trmnlp/api_client.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+
+require_relative 'config'
+
+module TRMNLP
+  class APIClient
+    def initialize(config)
+      @config = config
+    end
+
+    def get_me
+      response = conn.get('me')
+
+      raise Error, "failed to fetch user info: #{response.status} #{response.body}" unless response.status == 200
+
+      JSON.parse(response.body)['data']
+    end
+
+    def get_plugin_settings
+      response = conn.get('plugin_settings')
+
+      raise Error, "failed to list plugin settings: #{response.status} #{response.body}" unless response.status == 200
+
+      JSON.parse(response.body)['data']
+    end
+
+    def get_plugin_setting_archive(id)
+      response = conn.get("plugin_settings/#{id}/archive")
+
+      unless response.status == 200
+        raise Error, "failed to download plugin settings archive: #{response.status} #{response.body}"
+      end
+
+      temp_file = Tempfile.new(["plugin_settings_#{id}", '.zip'])
+      temp_file.binmode
+      temp_file.write(response.body)
+      temp_file.rewind
+
+      # return the temp file IO
+      temp_file
+    end
+
+    def post_plugin_setting_archive(id, path)
+      filepart = Faraday::Multipart::FilePart.new(path, 'application/zip')
+
+      payload = {
+        file: filepart
+      }
+
+      response = conn.post("plugin_settings/#{id}/archive", payload)
+
+      filepart.close
+
+      unless response.status == 200
+        raise Error, "failed to upload plugin settings archive: #{response.status} #{response.body}"
+      end
+
+      JSON.parse(response.body)
+    end
+
+    def post_plugin_setting(params)
+      response = conn.post('plugin_settings', params.to_json, content_type: 'application/json')
+
+      raise Error, "failed to create plugin setting: #{response.status} #{response.body}" unless response.status == 200
+
+      JSON.parse(response.body)
+    end
+
+    def delete_plugin_setting(id)
+      response = conn.delete("plugin_settings/#{id}")
+
+      raise Error, "failed to delete plugin setting: #{response.status} #{response.body}" unless response.status == 204
+
+      true
+    end
+
+    private
+
+    attr_reader :config
+
+    def api_uri = config.app.api_uri
+
+    def conn
+      @conn ||= Faraday.new(url: api_uri, headers:) do |f|
+        f.request :multipart
+      end
+    end
+
+    def headers
+      {
+        'Authorization' => "Bearer #{config.app.api_key}",
+        'User-Agent' => "trmnlp/#{VERSION}"
+      }
+    end
+  end
+end

data/lib/trmnlp/app.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'sinatra'
+require 'sinatra/base'
+
+require_relative 'context'
+require_relative 'screen_generator'
+require_relative 'screenshot'
+
+module TRMNLP
+  class App < Sinatra::Base
+    # Sinatra settings
+    set :views, File.join(File.dirname(__FILE__), '..', '..', 'web', 'views')
+    set :public_folder, File.join(File.dirname(__FILE__), '..', '..', 'web', 'public')
+
+    helpers do
+      def format_bytes(bytes)
+        bytes < 1024 ? "#{bytes} bytes" : format('%.1f KB', bytes / 1024.0)
+      end
+
+      # NOTE: render_html.erb's layout yields raw plugin HTML through `<%= yield %>`,
+      # so a global `escape_html` setting would corrupt the render. Escape per-value.
+      def h(text)
+        Rack::Utils.escape_html(text.to_s)
+      end
+    end
+
+    def initialize(*args)
+      super
+
+      @context = settings.context
+      @poller = @context.poller
+      @renderer = @context.renderer
+      @user_data_assembler = @context.user_data_assembler
+      @transform_pipeline = @context.transform_pipeline
+      @watcher = @context.watcher
+      @screenshot = Screenshot.new(pool: settings.browser_pool)
+
+      @poller.poll_data
+
+      @watcher.start if @context.config.project.live_render?
+
+      @live_reload_clients = []
+      @watcher.on_change do |view, user_data|
+        payload = {
+          'type' => 'reload',
+          'view' => view,
+          'user_data' => user_data
+        }
+        message = "data: #{payload.to_json}\n\n"
+        @live_reload_clients.each { |queue| queue << message }
+      end
+    end
+
+    post '/webhook' do
+      @poller.put_webhook(request.body.read)
+      'OK'
+    end
+
+    get '/' do
+      redirect '/full'
+    end
+
+    get '/data' do
+      content_type :json
+      device = @user_data_assembler.device_from_params(params)
+      JSON.pretty_generate(@user_data_assembler.call(device:))
+    end
+
+    # Live reload is a one-directional server->browser push, so it uses
+    # server-sent events rather than a websocket. Each client gets a blocking
+    # queue; the stream thread parks on queue.pop until the watcher broadcasts.
+    get '/live_reload' do
+      content_type 'text/event-stream'
+      queue = Thread::Queue.new
+      @live_reload_clients << queue
+      stream(:keep_open) do |out|
+        out.callback { @live_reload_clients.delete(queue) }
+        out << queue.pop until out.closed?
+      end
+    end
+
+    get '/poll' do
+      @poller.poll_data
+      redirect back
+    end
+
+    Screen.all.each do |screen|
+      view = screen.name
+      get "/#{view}" do
+        @view = view
+        device = @user_data_assembler.device_from_params(params)
+        user_data = @user_data_assembler.call(device:)
+        @user_data = JSON.pretty_generate(user_data)
+        # Measured on compact JSON, the way the hosted service sizes merge variables.
+        @payload_size = JSON.generate(user_data).bytesize
+        @live_reload = @context.config.project.live_render?
+        @transform_error = @transform_pipeline.error
+
+        erb :index
+      end
+
+      get "/render/#{view}.html" do
+        @renderer.render_full_page(view, params)
+      end
+
+      get "/render/#{view}.png" do
+        @view = view
+        html = @renderer.render_full_page(view, params)
+        temp_image = render_png(html, params)
+
+        send_file temp_image.path, type: 'image/png', disposition: 'inline'
+
+        temp_image.close
+        temp_image.unlink
+      end
+    end
+
+    private
+
+    # ScreenGenerator is request-scoped — it carries the per-request width,
+    # height, and color_depth — so it is built here rather than on the shared
+    # Context graph. Screenshots are a serve-only concern and would not belong
+    # on a Context shared by every command (build, lint, push, ...).
+    def render_png(html, params)
+      ScreenGenerator.new(html, screenshot: @screenshot,
+                                width: params[:width]&.to_i,
+                                height: params[:height]&.to_i,
+                                color_depth: params[:color_depth]&.to_i).process
+    end
+  end
+end

data/lib/trmnlp/browser_pool.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  class BrowserPool
+    def initialize(driver_factory:, max_size: 2)
+      @driver_factory = driver_factory
+      @max_size = max_size
+      @drivers = []
+      @available = Queue.new
+      @mutex = Mutex.new
+      @shutdown = false
+
+      at_exit { shutdown }
+    end
+
+    def with_driver
+      driver = checkout
+      yield driver
+    ensure
+      checkin(driver) if driver
+    end
+
+    def shutdown
+      @mutex.synchronize do
+        return if @shutdown
+
+        @shutdown = true
+        @drivers.each do |driver|
+          driver.quit
+        rescue StandardError
+          nil
+        end
+        @drivers.clear
+      end
+    end
+
+    private
+
+    def checkout
+      driver = acquire
+      healthy?(driver) ? driver : recycle(driver)
+    end
+
+    def acquire
+      pop_available || build_new || @available.pop
+    end
+
+    def pop_available
+      @available.pop(true)
+    rescue StandardError
+      nil
+    end
+
+    def build_new
+      @mutex.synchronize do
+        return nil if @drivers.size >= @max_size
+
+        @driver_factory.call.tap { |d| @drivers << d }
+      end
+    end
+
+    def healthy?(driver)
+      driver.title
+      true
+    rescue StandardError
+      false
+    end
+
+    def recycle(driver)
+      @mutex.synchronize do
+        @drivers.delete(driver)
+        @driver_factory.call.tap { |d| @drivers << d }
+      end
+    end
+
+    def checkin(driver)
+      return if @shutdown
+
+      @available.push(driver)
+    end
+  end
+end

data/lib/trmnlp/cli.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+require_relative '../trmnlp'
+require_relative '../trmnlp/commands'
+
+module TRMNLP
+  class CLI < Thor
+    package_name 'trmnlp'
+
+    class_option :dir, type: :string, default: Dir.pwd, aliases: '-d',
+                       desc: 'Plugin project directory'
+
+    class_option :quiet, type: :boolean, default: false, desc: 'Suppress output', aliases: '-q'
+
+    def self.exit_on_failure? = true
+
+    def self.default_bind = File.exist?('/.dockerenv') ? '0.0.0.0' : '127.0.0.1'
+
+    desc 'build', 'Generate static HTML files'
+    def build
+      Commands::Build.run(options)
+    end
+
+    desc 'login', 'Authenticate with TRMNL server'
+    def login
+      Commands::Login.run(options)
+    end
+
+    desc 'init NAME', 'Start a new plugin project'
+    method_option :skip_liquid, type: :boolean, default: false, desc: 'Skip generating liquid templates'
+    def init(name)
+      Commands::Init.run(options, name)
+    end
+
+    desc 'clone NAME ID', 'Copy a plugin project from TRMNL server'
+    def clone(name, id)
+      Commands::Clone.run(options, name, id)
+    end
+
+    desc 'list', 'List private plugins from TRMNL server'
+    def list
+      Commands::List.run(options)
+    end
+
+    desc 'pull', 'Download latest plugin settings from TRMNL server'
+    method_option :force, type: :boolean, default: false, aliases: '-f',
+                          desc: 'Skip confirmation prompts'
+    method_option :id, type: :string, aliases: '-i', desc: 'Plugin settings ID'
+    def pull
+      Commands::Pull.run(options)
+    end
+
+    desc 'push', 'Upload latest plugin settings to TRMNL server'
+    method_option :force, type: :boolean, default: false, aliases: '-f',
+                          desc: 'Skip confirmation prompts'
+    method_option :id, type: :string, aliases: '-i', desc: 'Plugin settings ID'
+    def push
+      Commands::Push.run(options)
+    end
+
+    desc 'lint', 'Check plugin code against TRMNL best practices'
+    def lint
+      # Exit non-zero when issues are found so CI pipelines can gate on it.
+      exit(1) unless Commands::Lint.run(options)
+    end
+
+    desc 'serve', 'Start a local dev server'
+    method_option :bind, type: :string, default: default_bind, aliases: '-b', desc: 'Bind address'
+    method_option :port, type: :numeric, default: 4567, aliases: '-p', desc: 'Port number'
+    def serve
+      Commands::Serve.run(options)
+    end
+
+    desc 'version', 'Show version'
+    def version
+      puts VERSION
+    end
+  end
+end

data/lib/trmnlp/commands/base.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative '../context'
+require_relative '../form_field'
+require_relative '../reporter'
+
+module TRMNLP
+  module Commands
+    class Base
+      def self.run(input, *)
+        options = options_from(input)
+        reporter = Reporter.new(quiet: options.quiet)
+        new(context: Context.new(options.dir, reporter:), options:, reporter:).call(*)
+      end
+
+      # NOTE: Thor only includes flags the user actually passed, but Data.define
+      # requires every member. We pad missing members with nil so partial Thor
+      # hashes round-trip into a fully-populated typed Options struct.
+      def self.options_from(input)
+        return input if input.is_a?(self::Options)
+
+        hash = input.to_h.transform_keys(&:to_sym)
+        self::Options.new(**self::Options.members.to_h { [it, hash[it]] })
+      end
+
+      def initialize(context:, options:, reporter: nil)
+        raise ArgumentError, "options must be a #{self.class}::Options" unless options.is_a?(self.class::Options)
+
+        @context = context
+        @options = options
+        @reporter = reporter || Reporter.new(quiet: options.quiet)
+      end
+
+      def call
+        raise NotImplementedError
+      end
+
+      protected
+
+      attr_accessor :options, :context, :reporter
+
+      def config = context.config
+      def paths = context.paths
+
+      def authenticate!
+        raise NotLoggedIn, 'please run `trmnlp login`' unless config.app.logged_in?
+      end
+
+      # Non-blocking: warn about malformed settings.yml custom_fields so a
+      # plugin author notices before the field misbehaves in production.
+      def report_form_field_warnings
+        FormField.validate_all(config.plugin.custom_field_definitions).each do |warning|
+          reporter.info("warning: settings.yml custom_fields — #{warning}")
+        end
+      end
+
+      def prompt(message)
+        print message
+        $stdin.gets.chomp
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/build.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module TRMNLP
+  module Commands
+    class Build < Base
+      Options = Data.define(:dir, :quiet)
+
+      def call
+        context.validate!
+        report_form_field_warnings
+        context.poller.poll_data
+        context.paths.create_build_dir
+
+        Screen.all.each do |screen|
+          output_path = context.paths.build_dir.join("#{screen.name}.html")
+          reporter.info "Writing #{output_path}..."
+          output_path.write(context.renderer.render_full_page(screen.name))
+        end
+
+        reporter.info 'Done!'
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/clone.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'init'
+require_relative 'pull'
+
+module TRMNLP
+  module Commands
+    class Clone < Base
+      Options = Data.define(:dir, :quiet)
+
+      def call(directory_name, id)
+        authenticate!
+
+        destination_path = Pathname.new(options.dir).join(directory_name)
+        raise DirectoryExists, "directory #{destination_path} already exists, aborting" if destination_path.exist?
+
+        Init.run({ dir: options.dir, skip_liquid: true, quiet: true }, directory_name)
+
+        Pull.run({ dir: destination_path.to_s, force: true, id: id })
+
+        reporter.info <<~HEREDOC
+
+          To start the local server:
+
+              cd #{Pathname.new(destination_path).relative_path_from(Dir.pwd)} && trmnlp serve
+        HEREDOC
+      end
+
+      private
+
+      def template_dir = paths.templates_dir.join('init')
+    end
+  end
+end

data/lib/trmnlp/commands/init.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+require_relative 'base'
+
+module TRMNLP
+  module Commands
+    class Init < Base
+      Options = Data.define(:dir, :quiet, :skip_liquid)
+
+      def call(name)
+        destination_dir = Pathname.new(options.dir).join(name)
+
+        unless destination_dir.exist?
+          reporter.info "Creating #{destination_dir}"
+          destination_dir.mkpath
+        end
+
+        template_dir.glob('**/{*,.*}').each do |source_pathname|
+          next if source_pathname.directory?
+          next if options.skip_liquid && source_pathname.extname == '.liquid'
+
+          relative_pathname = source_pathname.relative_path_from(template_dir)
+          destination_pathname = destination_dir.join(relative_pathname)
+          destination_pathname.dirname.mkpath
+
+          if destination_pathname.exist?
+            answer = prompt("#{destination_pathname} already exists. Overwrite? (y/n): ").downcase
+            if answer != 'y'
+              reporter.info "Skipping #{destination_pathname}"
+              next
+            end
+          end
+
+          reporter.info "Creating #{destination_pathname}"
+          FileUtils.cp(source_pathname, destination_pathname)
+        end
+
+        reporter.info <<~HEREDOC
+
+          To start the local server:
+
+              cd #{Pathname.new(destination_dir).relative_path_from(Dir.pwd)}
+              trmnlp serve
+
+          To publish the plugin:
+
+              trmnlp login
+              trmnlp push
+        HEREDOC
+      end
+
+      private
+
+      def template_dir = paths.templates_dir.join('init')
+    end
+  end
+end

data/lib/trmnlp/commands/lint.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../lint'
+
+module TRMNLP
+  module Commands
+    # Runs the markup best-practice checks and reports their findings.
+    class Lint < Base
+      Options = Data.define(:dir, :quiet)
+
+      def call
+        context.validate!
+        report
+        issues.empty?
+      end
+
+      private
+
+      def issues
+        @issues ||= TRMNLP::Lint::CHECKS.flat_map { |check| check.new(source).issues }.uniq
+      end
+
+      def source
+        @source ||= TRMNLP::Lint::Source.new(config:, paths:)
+      end
+
+      def report
+        return reporter.info(reporter.green('✓ All checks passed!')) if issues.empty?
+
+        reporter.info(reporter.yellow("#{issues.size} issue#{'s' if issues.size > 1} found:\n"))
+        issues.each_with_index { |issue, index| report_issue(issue, index) }
+        reporter.info('')
+      end
+
+      def report_issue(issue, index)
+        reporter.info("  #{index + 1}. #{issue[:message]}")
+        reporter.info("     Learn more: #{issue[:learn_more]}") if issue[:learn_more]
+      end
+    end
+  end
+end