trmnl_preview 0.7.0 → 0.8.0

data/lib/trmnlp/context.rb

@@ -1,238 +1,35 @@
-require 'active_support/time'
-require 'active_support/core_ext/hash/conversions'
-require 'erb'
-require 'faraday'
-require 'filewatcher'
-require 'json'
-require 'trmnl/liquid'
+# frozen_string_literal: true
 
 require_relative 'config'
 require_relative 'paths'
+require_relative 'poller'
+require_relative 'renderer'
+require_relative 'reporter'
+require_relative 'transform_pipeline'
+require_relative 'user_data_assembler'
+require_relative 'watcher'
 
 module TRMNLP
   class Context
-    attr_reader :config, :paths
-    
-    def initialize(root_dir)
+    attr_reader :config, :paths, :reporter
+
+    def initialize(root_dir, reporter: Reporter.new)
       @paths = Paths.new(root_dir)
       @config = Config.new(paths)
+      @reporter = reporter
     end
 
-    def validate!
-      raise Error, "not a plugin directory (did not find #{paths.trmnlp_config})" unless paths.valid?
-    end
-
-    def start_filewatcher
-      @filewatcher_thread ||= Thread.new do
-        loop do
-          begin
-            Filewatcher.new(config.project.watch_paths).watch do |changes|
-              config.project.reload!
-              config.plugin.reload!
-              new_user_data = user_data
-
-              views = changes.map { |path, _change| File.basename(path, '.liquid') }
-              views.each do |view|
-                @view_change_callback.call(view, new_user_data) if @view_change_callback
-              end
-            end
-          rescue => e
-            puts "Error during live render: #{e}"
-          end
-        end
-      end
-    end
-
-    def on_view_change(&block)
-      @view_change_callback = block
-    end
-
-    def user_data
-      merged_data = base_trmnl_data
-
-      if config.plugin.static?
-        merged_data.merge!(config.plugin.static_data)
-      elsif paths.user_data.exist?
-        merged_data.merge!(JSON.parse(paths.user_data.read))
-      end
-
-      # Praise be to ActiveSupport
-      merged_data.deep_merge!(config.project.user_data_overrides)
-    end
-
-    def poll_data
-      return unless config.plugin.polling?
-
-      data = {}
-
-      if config.plugin.polling_urls.empty?
-        raise Error, "config must specify polling_url or polling_urls"
-      end
-
-      config.plugin.polling_urls.each.with_index do |url, i|
-        verb = config.plugin.polling_verb.upcase
-
-        print "#{verb} #{url}... "
-
-        conn = Faraday.new(url:, headers: config.plugin.polling_headers)
-
-        case verb
-        when 'GET'
-          response = conn.get
-        when 'POST'
-          response = conn.post do |req|
-            req.body = config.plugin.polling_body
-          end
-        end
-
-        puts "received #{response.body.length} bytes (#{response.status} status)"
-        if response.status == 200
-          content_type = response.headers['content-type'].split(';').first.strip if response.headers.include?('content-type')
-          case content_type
-          when 'application/json', /^application\/.+\+json/
-            json = wrap_array(JSON.parse(response.body))
-          when 'text/xml', 'application/xml', /^application\/.+\+xml/
-            json = wrap_array(Hash.from_xml(response.body))
-          else
-            puts "unknown content type received: #{response.headers['content-type']}"
-            json = {}
-          end
-        else
-          json = {}
-          puts response.body
-        end
-        
-        if config.plugin.polling_urls.count == 1
-          # For a single polling URL, we just return the JSON directly
-          data = json
-          break
-        else
-          # Multiple URLs are namespaced by index
-          data["IDX_#{i}"] = json
-        end
-      end
-
-      write_user_data(data)
-
-      data
-    rescue StandardError => e
-      puts "error: #{e.message}"
-      {}
-    end
-
-    def put_webhook(payload)
-      data = wrap_array(JSON.parse(payload))
-      write_user_data(data)
-    rescue
-      puts "webhook error: #{e.message}"
-    end
-
-    def render_liquid_template(view)
-      template_path = paths.template(view)
-      return "Missing template: #{template_path}" unless template_path.exist?
-
-      shared_template_path = paths.shared_template
-      if shared_template_path.exist?
-        full_markup = shared_template_path.read + template_path.read
-      else
-        full_markup = template_path.read
-      end
-
-      user_template = Liquid::Template.parse(full_markup, environment: liquid_environment)
-      user_template.render(user_data)
-    rescue StandardError => e
-      e.message
-    end
-
-    def render_full_page(view, params = {})
-      template = paths.render_template.read
-      
-      ERB.new(template).result(TemplateBinding.new(self, view, params).get_binding do
-        render_liquid_template(view)
-      end)
-    end
-
-    def screen_classes(classes = 'screen')
-      classes << ' screen--no-bleed' if config.plugin.no_screen_padding == 'yes'
-      classes
-    end
-
-    private 
-
-    # bindings must match the `GET /render/{view}.html` route in app.rb
-    class TemplateBinding
-      def initialize(context, view, params)
-        @view = view
-        @screen_classes = context.screen_classes(params[:screen_classes])
+    # 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 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:)
+    def watcher = @watcher ||= Watcher.new(config:, user_data_assembler:, transform_pipeline:, reporter:)
 
-        case view
-        when 'half_horizontal'
-          @mashup_classes = 'mashup mashup--1Tx1B'
-        when 'half_vertical'
-          @mashup_classes = 'mashup mashup--1Lx1R'
-        when 'quadrant'
-          @mashup_classes = 'mashup mashup--2x2'
-        end
-      end
-
-      def get_binding = binding
-    end
-
-    def wrap_array(json)
-      json.is_a?(Array) ? { data: json } : json
-    end
-
-    def base_trmnl_data
-      tz = ActiveSupport::TimeZone.find_tzinfo(config.project.time_zone)
-      time_zone_iana = tz.name
-      time_zone_name = ActiveSupport::TimeZone::MAPPING.invert[time_zone_iana] || time_zone_iana
-      utc_offset = tz.utc_offset
-
-      {
-        'trmnl' => {
-          'user' => {
-            'name' => 'name',
-            'first_name' => 'first_name',
-            'last_name' => 'last_name',
-            'locale' => 'en',
-            'time_zone' => time_zone_name,
-            'time_zone_iana' => time_zone_iana,
-            'utc_offset' => utc_offset,
-          },
-          'device' => {
-            'friendly_id' => 'ABC123',
-            'percent_charged' => 85.0,
-            'wifi_strength' => 90,
-            'height' => 480,
-            'width' => 800
-          },
-          'system' => {
-            'timestamp_utc' => Time.now.utc.to_i,
-          },
-          'plugin_settings' => {
-            'instance_name' => 'instance_name',
-            'strategy' => config.plugin.strategy,
-            'dark_mode' => config.plugin.dark_mode,
-            'polling_headers' => config.plugin.polling_headers_encoded,
-            'polling_url' => config.plugin.polling_url_text,
-            'custom_fields_values' => config.project.custom_fields
-          }
-        }
-      }
-    end
-
-    def liquid_environment
-      @liquid_environment ||= TRMNL::Liquid.build_environment do |env|
-        config.project.user_filters.each do |module_name, relative_path|
-          require paths.root_dir.join(relative_path)
-          env.register_filter(Object.const_get(module_name))
-        end
-      end
-    end
-
-    def write_user_data(data)
-      paths.create_cache_dir
-      paths.user_data.write(JSON.generate(data))
+    def validate!
+      raise NotAPlugin, "not a plugin directory (did not find #{paths.trmnlp_config})" unless paths.valid?
     end
   end
 end

data/lib/trmnlp/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  class Error < StandardError; end
+
+  class NotLoggedIn         < Error; end
+  class NotAPlugin          < Error; end
+  class DirectoryExists     < Error; end
+  class Aborted             < Error; end
+  class PluginIdRequired    < Error; end
+  class InvalidApiKey       < Error; end
+  class AuthenticationFailed < Error; end
+  class InvalidConfig       < Error; end
+  class RenderError         < Error; end
+end

data/lib/trmnlp/form_field.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module TRMNLP
+  # Validates entries in a plugin's settings.yml custom_fields list.
+  #
+  # The required keys and field-type allowlist are vendored from the hosted
+  # service into db/data/form_fields.yml — the same db/data convention
+  # FrameworkVersion uses. See that file's header for the refresh policy.
+  #
+  # Validation is intentionally lenient: it mirrors the hosted service's
+  # live form-field validation (presence checks only) and does NOT reject
+  # unknown keys — the hosted form views read far more keys than they
+  # validate.
+  module FormField
+    DATA_PATH = File.expand_path('../../db/data/form_fields.yml', __dir__)
+
+    def self.schema = @schema ||= YAML.safe_load_file(DATA_PATH).freeze
+    def self.required_keys = schema.fetch('required_keys')
+    def self.field_types = schema.fetch('field_types')
+
+    def self.multi_select?(field) = field['field_type'] == 'select' && field['multiple']
+
+    def self.validate(field)
+      warnings = []
+
+      required_keys.each do |key|
+        warnings << "missing required key: #{key}" unless field.key?(key) || field.key?(key.to_sym)
+      end
+
+      type = field['field_type'] || field[:field_type]
+      warnings << "unknown field_type: #{type}" if type && !field_types.include?(type)
+
+      warnings
+    end
+
+    def self.validate_all(fields)
+      Array(fields).flat_map { |field| validate(field) }
+    end
+  end
+end

data/lib/trmnlp/framework_version.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module TRMNLP
+  # Represents a TRMNL design-system framework version, so plugins can
+  # pin (or float to "latest") the CSS/JS bundle they render against,
+  # both in production and locally.
+  class FrameworkVersion
+    include Comparable
+
+    DEFAULT_ASSET_HOST = 'https://trmnl.com'
+    DATA_PATH = File.expand_path('../../db/data/framework_versions.yml', __dir__)
+
+    attr_reader :number
+
+    def self.config = @config ||= YAML.load_file(DATA_PATH).freeze
+
+    def self.version_numbers = config.fetch('versions').map { |v| v['number'] }.freeze
+
+    def self.latest = new(config.fetch('latest'))
+
+    # Suitable for showing in a `select` form field. Pinnable versions are
+    # ordered newest-first by semantic version — never by manifest order.
+    def self.options
+      newest_first = version_numbers.sort_by { |number| Gem::Version.new(number) }.reverse
+      [{ "Always track latest (currently v#{latest.number})" => 'latest' }] +
+        newest_first.map { |number| { "v#{number}" => number } }
+    end
+
+    def initialize(number, asset_host: DEFAULT_ASSET_HOST)
+      @asset_host = asset_host
+
+      if number.nil? || number == 'latest'
+        @number = self.class.config.fetch('latest')
+        @pinned = false
+      elsif self.class.version_numbers.include?(number)
+        @number = number
+        @pinned = true
+      else
+        raise ArgumentError, "unknown framework version: #{number}"
+      end
+    end
+
+    def pinned? = @pinned
+
+    def css_url = "#{@asset_host}/css/#{path_segment}/plugins.css"
+
+    def js_url = "#{@asset_host}/js/#{path_segment}/plugins.js"
+
+    def ==(other) = other.is_a?(self.class) && number == other.number
+
+    def <=>(other)
+      return nil unless other.is_a?(self.class)
+
+      Gem::Version.new(number) <=> Gem::Version.new(other.number)
+    end
+
+    def as_json(*) = number
+
+    def to_s = number
+
+    private
+
+    # When pinned, requests assets at /css/<version>/plugins.css to lock
+    # behavior; otherwise hit /css/latest/ for live updates.
+    def path_segment = pinned? ? @number : 'latest'
+  end
+end

data/lib/trmnlp/image_quantizer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'mini_magick'
+require 'tempfile'
+require 'fileutils'
+
+module TRMNLP
+  class ImageQuantizer
+    MIN_DEPTH = 1
+    MAX_DEPTH = 8
+
+    def initialize(depth:)
+      @depth = clamp(depth)
+    end
+
+    def call(path)
+      tmp = Tempfile.new(['mono', '.png'])
+      tmp.close
+      quantize(path, tmp.path)
+      FileUtils.mv(tmp.path, path, force: true)
+    end
+
+    private
+
+    def quantize(src, dst)
+      MiniMagick.convert do |m|
+        m << src
+        m.colorspace 'Gray'
+        m.dither 'FloydSteinberg'
+        apply_depth(m)
+        m.depth @depth
+        m.define "png:bit-depth=#{@depth}"
+        m.strip
+        m << dst
+      end
+    end
+
+    def apply_depth(m)
+      if @depth == 1
+        # NOTE: 1-bit only has black/white, so a halftone remap simulates gray
+        # via dithering patterns. Skipping this collapses photos to pure
+        # silhouettes.
+        m.remap 'pattern:gray50'
+        m.posterize 2
+        m.colors 2
+        m.type 'Bilevel'
+      else
+        levels = 2**@depth
+        m.posterize levels
+        m.colors levels
+      end
+    end
+
+    def clamp(depth)
+      [[depth.to_i, MIN_DEPTH].max, MAX_DEPTH].min
+    end
+  end
+end

data/lib/trmnlp/lint/check.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module Lint
+    # Base class for a single best-practice check. A subclass declares a
+    # MESSAGE constant (and optionally LEARN_MORE) and implements #pass?.
+    # Checks that surface a variable number of findings override #issues.
+    class Check
+      def initialize(source)
+        @source = source
+      end
+
+      def issues
+        pass? ? [] : [issue]
+      end
+
+      private
+
+      attr_reader :source
+
+      def pass?
+        raise NotImplementedError
+      end
+
+      def issue
+        learn_more = self.class.const_defined?(:LEARN_MORE) ? self.class::LEARN_MORE : nil
+        { message: self.class::MESSAGE, learn_more: }.compact
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/custom_fields_used.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports custom fields declared in .trmnlp.yml that never appear in the
+      # polling settings or the markup — one finding per unused field.
+      class CustomFieldsUsed < Check
+        SETTINGS_KEYS = %w[polling_url polling_headers polling_body].freeze
+
+        def issues
+          source.custom_field_values.keys.reject { |keyname| used?(keyname) }.map do |keyname|
+            { message: "Custom field '#{keyname}' is not used in form fields or markup." }
+          end
+        end
+
+        private
+
+        def used?(keyname)
+          pattern = /#{Regexp.escape(keyname)}/
+          searchable_settings.match?(pattern) || source.all_markup.match?(pattern)
+        end
+
+        def searchable_settings
+          @searchable_settings ||= SETTINGS_KEYS.filter_map { |key| source.settings[key] }.join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/form_fields_valid.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+require_relative '../../form_field'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Validates settings.yml custom_fields against the FormField schema —
+      # the same source serve/build use for their startup warnings.
+      class FormFieldsValid < Check
+        def issues
+          FormField.validate_all(source.custom_field_definitions).map do |warning|
+            { message: "settings.yml custom_fields — #{warning}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/highcharts_animations_disabled.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class HighchartsAnimationsDisabled < Check
+        MESSAGE = 'Highcharts should have animations disabled.'
+        LEARN_MORE = 'https://trmnl.com/framework/chart'
+
+        private
+
+        def pass?
+          markup = source.all_markup
+          return true unless markup.downcase.include?('highcharts')
+
+          markup.match?(/animation:\s{0,6}false/)
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/highcharts_elements_unique.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class HighchartsElementsUnique < Check
+        MESSAGE = 'To avoid variable shadowing across charts in multiple layouts, ' \
+                  'use the append_random filter for your Highcharts elements.'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10347358-custom-plugin-filters'
+
+        private
+
+        def pass?
+          markup = source.all_markup
+          return true unless markup.downcase.include?('highcharts')
+
+          markup.match?(/append_random/)
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/image_links_reachable.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Flags static <img> URLs that answer with a non-success status. A
+      # network failure (offline, DNS, timeout) is NOT a plugin defect, so
+      # those are skipped rather than reported as one.
+      class ImageLinksReachable < Check
+        MESSAGE = 'One or more <img> tags has a static "src" URL that does not ' \
+                  'respond to HTTP GET requests with a success code.'
+        TIMEOUT = 5
+        UNREACHABLE = [SocketError, Net::OpenTimeout, Net::ReadTimeout,
+                       Errno::ECONNREFUSED, Errno::EHOSTUNREACH, OpenSSL::SSL::SSLError].freeze
+
+        private
+
+        def pass? = static_image_urls.all? { |url| reachable?(url) }
+
+        def static_image_urls
+          source.view_markup.values
+                .flat_map { |html| html.scan(/<img[^>]+src\s*=\s*["']([^"']+)["']/i).flatten }
+                .map(&:strip)
+                .reject { |src| src.empty? || src.include?('{{') || src.start_with?('data:') }
+        end
+
+        def reachable?(url)
+          return false unless url.match?(%r{\Ahttps?://})
+
+          response = fetch(URI.parse(url))
+          response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPRedirection)
+        rescue *UNREACHABLE
+          true
+        rescue StandardError
+          false
+        end
+
+        def fetch(uri)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
+                                              open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+            http.get(uri.request_uri)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/layouts_have_content.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class LayoutsHaveContent < Check
+        MIN_CONTENT_LENGTH = 10
+        MESSAGE = 'Some markup layouts are empty, please provide basic treatment.'
+
+        private
+
+        # A view passes when either its own markup or the shared markup
+        # carries real content — mirrors the hosted behaviour.
+        def pass?
+          source.view_markup.values.all? do |markup|
+            [markup.length, source.shared_markup.length].max >= MIN_CONTENT_LENGTH
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/limited_inline_styles.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class LimitedInlineStyles < Check
+        MAX_INLINE_STYLES = 6
+        PROPERTIES = %w[
+          justify-content padding margin background-color
+          border-radius text-align object-fit font-size
+        ].freeze
+        MESSAGE = 'Markup uses too many inline styles, add more native Framework classes.'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/11395668-recipe-best-practices#h_3a3eab0712'
+
+        private
+
+        def pass?
+          count = PROPERTIES.sum { |property| source.all_markup.scan(property).size }
+          count <= MAX_INLINE_STYLES
+        end
+      end
+    end
+  end
+end