trmnl_preview 0.7.1 → 0.8.1

data/lib/trmnlp/app.rb

@@ -1,103 +1,142 @@
+# frozen_string_literal: true
 
-require 'faye/websocket'
 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
+
+      # Colour-codes the payload badge so an author notices when merge
+      # variables approach the size the hosted service starts rejecting.
+      # KB = 1024, matching format_bytes.
+      def payload_size_class(bytes)
+        return 'payload-size--over' if bytes >= 100 * 1024
+        return 'payload-size--warn' if bytes >= 75 * 1024
+
+        'payload-size--ok'
+      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)
 
-      @context.poll_data
+      @poller.poll_data
 
-      @context.start_filewatcher if @context.config.project.live_render?
+      @watcher.start if @context.config.project.live_render?
 
       @live_reload_clients = []
-      @context.on_view_change do |view, user_data|
-        @live_reload_clients.each do |ws|
-          payload = {
-            'type' => 'reload',
-            'view' => view,
-            'user_data' => user_data
-          }
-
-          ws.send(payload.to_json)
-        end
+      @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
-      @context.put_webhook(request.body.read)
-      "OK"
+      @poller.put_webhook(request.body.read)
+      'OK'
     end
-    
+
     get '/' do
       redirect '/full'
     end
 
     get '/data' do
       content_type :json
-      JSON.pretty_generate(@context.user_data)
+      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
-      ws = Faye::WebSocket.new(request.env)
-
-      ws.on(:open) do |event|
-        @live_reload_clients << ws
+      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
-  
-      ws.on(:close) do |event|
-        @live_reload_clients.delete(ws)
-      end
-  
-      ws.rack_response
     end
 
     get '/poll' do
-      @context.poll_data
+      @poller.poll_data
       redirect back
     end
-    
-    VIEWS.each do |view|
+
+    Screen.all.each do |screen|
+      view = screen.name
       get "/#{view}" do
         @view = view
-        @user_data = JSON.pretty_generate(@context.user_data)
+        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
-        @context.render_full_page(view, params)
+        @renderer.render_full_page(view, params)
       end
-      
+
       get "/render/#{view}.png" do
         @view = view
-        html = @context.render_full_page(view, params)
-
-        # Parse optional rendering params (sent by the web UI for PNG output)
-        width = params[:width] && params[:width].to_i
-        height = params[:height] && params[:height].to_i
-        color_depth = params[:color_depth] && params[:color_depth].to_i
+        html = @renderer.render_full_page(view, params)
+        temp_image = render_png(html, params)
 
-        generator = ScreenGenerator.new(html, image: true, width: width, height: height, color_depth: color_depth)
-        temp_image = generator.process
-        
         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
+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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'thor'
 
 require_relative '../trmnlp'
@@ -8,7 +10,7 @@ module TRMNLP
     package_name 'trmnlp'
 
     class_option :dir, type: :string, default: Dir.pwd, aliases: '-d',
-                  desc: 'Plugin project directory'
+                       desc: 'Plugin project directory'
 
     class_option :quiet, type: :boolean, default: false, desc: 'Suppress output', aliases: '-q'
 
@@ -17,47 +19,62 @@ module TRMNLP
     def self.default_bind = File.exist?('/.dockerenv') ? '0.0.0.0' : '127.0.0.1'
 
     desc 'build', 'Generate static HTML files'
+    method_option :png, type: :boolean, default: false, desc: 'Also render a PNG per view'
+    method_option :width, type: :numeric, desc: 'PNG width in pixels (with --png)'
+    method_option :height, type: :numeric, desc: 'PNG height in pixels (with --png)'
+    method_option :color_depth, type: :numeric, desc: 'PNG bit depth: 1, 2, or 4 (with --png)'
     def build
-      Commands::Build.new(options).call
+      Commands::Build.run(options)
     end
 
     desc 'login', 'Authenticate with TRMNL server'
     def login
-      Commands::Login.new(options).call
+      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.new(options).call(name)
+      Commands::Init.run(options, name)
     end
 
     desc 'clone NAME ID', 'Copy a plugin project from TRMNL server'
     def clone(name, id)
-      Commands::Clone.new(options).call(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'
+                          desc: 'Skip confirmation prompts'
     method_option :id, type: :string, aliases: '-i', desc: 'Plugin settings ID'
     def pull
-      Commands::Pull.new(options).call
+      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'
+                          desc: 'Skip confirmation prompts'
     method_option :id, type: :string, aliases: '-i', desc: 'Plugin settings ID'
     def push
-      Commands::Push.new(options).call
+      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.new(options).call
+      Commands::Serve.run(options)
     end
 
     desc 'version', 'Show version'
@@ -65,4 +82,4 @@ module TRMNLP
       puts VERSION
     end
   end
-end
+end

data/lib/trmnlp/commands/base.rb

@@ -1,15 +1,34 @@
-require 'thor/core_ext/hash_with_indifferent_access'
+# frozen_string_literal: true
 
 require_relative '../context'
+require_relative '../form_field'
+require_relative '../reporter'
 
 module TRMNLP
   module Commands
     class Base
-      include Thor::CoreExt
+      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)
 
-      def initialize(options = HashWithIndifferentAccess.new)
-        @options = HashWithIndifferentAccess.new(options)
-        @context = Context.new(@options.dir)
+        @context = context
+        @options = options
+        @reporter = reporter || Reporter.new(quiet: options.quiet)
       end
 
       def call
@@ -18,17 +37,21 @@ module TRMNLP
 
       protected
 
-      attr_accessor :options, :context
+      attr_accessor :options, :context, :reporter
 
       def config = context.config
       def paths = context.paths
 
       def authenticate!
-        raise Error, "please run `trmnlp login`" unless config.app.logged_in?
+        raise NotLoggedIn, 'please run `trmnlp login`' unless config.app.logged_in?
       end
 
-      def output(message)
-        puts(message) unless options.quiet?
+      # 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(reporter.yellow("warning: settings.yml custom_fields — #{warning}"))
+        end
       end
 
       def prompt(message)
@@ -37,4 +60,4 @@ module TRMNLP
       end
     end
   end
-end
+end

data/lib/trmnlp/commands/build.rb

@@ -1,21 +1,68 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
 require_relative 'base'
+require_relative '../browser_pool'
+require_relative '../firefox_driver'
+require_relative '../screen_generator'
+require_relative '../screenshot'
 
 module TRMNLP
   module Commands
     class Build < Base
+      Options = Data.define(:dir, :quiet, :png, :width, :height, :color_depth)
+
       def call
         context.validate!
-        context.poll_data
+        report_form_field_warnings
+        context.poller.poll_data
         context.paths.create_build_dir
 
-        VIEWS.each do |view|
-          output_path = context.paths.build_dir.join("#{view}.html")
-          output "Writing #{output_path}..."
-          output_path.write(context.render_full_page(view))
-        end
-  
-        output "Done!"
+        Screen.all.each { |screen| build_screen(screen) }
+
+        reporter.info 'Done!'
+      ensure
+        @browser_pool&.shutdown
+      end
+
+      private
+
+      def build_screen(screen)
+        html = context.renderer.render_full_page(screen.name)
+        write_html(screen.name, html)
+        write_png(screen.name, html) if options.png
+      end
+
+      def write_html(view, html)
+        path = context.paths.build_dir.join("#{view}.html")
+        reporter.info "Writing #{path}..."
+        path.write(html)
+      end
+
+      # --png is additive: the HTML is rendered either way, so it stays on
+      # disk alongside the PNG rather than being replaced by it.
+      def write_png(view, html)
+        path = context.paths.build_dir.join("#{view}.png")
+        reporter.info "Writing #{path}..."
+        image = screen_generator(html).process
+        FileUtils.cp(image.path, path)
+      ensure
+        image&.close!
+      end
+
+      # --width/--height/--color-depth are optional; nil lets ScreenGenerator
+      # fall back to 800x480 and the screen--Nbit depth sniffed from the markup.
+      def screen_generator(html)
+        ScreenGenerator.new(html, screenshot:, width: options.width,
+                                  height: options.height, color_depth: options.color_depth)
+      end
+
+      def screenshot = @screenshot ||= Screenshot.new(pool: browser_pool)
+
+      def browser_pool
+        @browser_pool ||= BrowserPool.new(driver_factory: FirefoxDriver.method(:build))
       end
     end
   end
-end
+end

data/lib/trmnlp/commands/clone.rb

@@ -1,24 +1,29 @@
+# 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 Error, "directory #{destination_path} already exists, aborting" if destination_path.exist?
+        raise DirectoryExists, "directory #{destination_path} already exists, aborting" if destination_path.exist?
 
-        Init.new(dir: options.dir, skip_liquid: true, quiet: true).call(directory_name)
+        Init.run({ dir: options.dir, skip_liquid: true, quiet: true }, directory_name)
 
-        Pull.new(dir: destination_path.to_s, force: true, id: id).call
+        Pull.run({ dir: destination_path.to_s, force: true, id: id })
 
-        output <<~HEREDOC
+        reporter.info <<~HEREDOC
 
-        To start the local server:
+          To start the local server:
 
-            cd #{Pathname.new(destination_path).relative_path_from(Dir.pwd)} && trmnlp serve
+              cd #{Pathname.new(destination_path).relative_path_from(Dir.pwd)} && trmnlp serve
         HEREDOC
       end
 
@@ -27,4 +32,4 @@ module TRMNLP
       def template_dir = paths.templates_dir.join('init')
     end
   end
-end
+end

data/lib/trmnlp/commands/init.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fileutils'
 
 require_relative 'base'
@@ -5,11 +7,13 @@ 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?
-          output "Creating #{destination_dir}"
+          reporter.info "Creating #{destination_dir}"
           destination_dir.mkpath
         end
 
@@ -20,36 +24,40 @@ module TRMNLP
           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'
-              output "Skipping #{destination_pathname}"
+              reporter.info "Skipping #{destination_pathname}"
               next
             end
           end
 
-          output "Creating #{destination_pathname}"
+          reporter.info "Creating #{destination_pathname}"
           FileUtils.cp(source_pathname, destination_pathname)
+          # NOTE: cp preserves the source mode. Templates installed read-only
+          # (e.g. NixOS /nix/store is 0444) would leave the author unable to
+          # edit their own project. Add owner-write; keep any exec bit.
+          destination_pathname.chmod(destination_pathname.stat.mode | 0o200)
         end
 
-        output <<~HEREDOC
+        reporter.info <<~HEREDOC
 
-        To start the local server:
+          To start the local server:
 
-            cd #{Pathname.new(destination_dir).relative_path_from(Dir.pwd)}
-            trmnlp serve
+              cd #{Pathname.new(destination_dir).relative_path_from(Dir.pwd)}
+              trmnlp serve
 
-        To publish the plugin:
+          To publish the plugin:
 
-            trmnlp login
-            trmnlp push
+              trmnlp login
+              trmnlp push
         HEREDOC
       end
 
       private
 
-      def template_dir = paths.templates_dir.join('init')  
+      def template_dir = paths.templates_dir.join('init')
     end
   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