trmnl_preview 0.7.2 → 0.8.0

data/lib/trmnlp/commands/list.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class List < Base
+      Options = Data.define(:dir, :quiet)
+
+      PRIVATE_PLUGIN_ID = 37
+
+      def call
+        authenticate!
+
+        api = APIClient.new(config)
+        response = api.get_plugin_settings
+        plugins = (response || [])
+                  .select { |p| p['plugin_id'] == PRIVATE_PLUGIN_ID }
+                  .sort_by { |p| (p['name'] || '').downcase }
+
+        if plugins.empty?
+          reporter.info 'No plugins found.'
+          return
+        end
+
+        reporter.info "Your plugins:\n\n"
+        reporter.info '  ID        NAME'
+        reporter.info "  #{'-' * 50}"
+
+        plugins.each do |plugin|
+          reporter.info format('  %-8s  %s', plugin['id'], plugin['name'])
+        end
+
+        reporter.info "\nTo clone a plugin:"
+        reporter.info '    trmnlp clone [folder_name] [id]'
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/login.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Login < Base
+      Options = Data.define(:dir, :quiet)
+
+      def call
+        if config.app.logged_in?
+          anonymous_key = config.app.api_key[0..10] + ('*' * (config.app.api_key.length - 11))
+          reporter.info "Currently authenticated as: #{anonymous_key}"
+          confirm = prompt('You are already authenticated. Do you want to re-authenticate? (y/N): ')
+          return unless confirm.strip.downcase == 'y'
+        end
+
+        reporter.info "Please visit #{config.app.account_uri} to grab your API key, then paste it here."
+
+        api_key = prompt('API Key: ')
+        raise InvalidApiKey, 'API key cannot be empty' if api_key.empty?
+        unless api_key.start_with?('user_')
+          raise InvalidApiKey,
+                'Invalid API key; did you copy it from the right place?'
+        end
+
+        config.app.api_key = api_key
+
+        api_client = APIClient.new(config)
+        begin
+          user_info = api_client.get_me
+          reporter.info "Authenticated as #{user_info['name']} (#{user_info['email']})"
+          config.app.save
+          reporter.info "Saved changes to #{paths.app_config}"
+        rescue StandardError => e
+          raise AuthenticationFailed, "Authentication failed; changes were not saved.\n#{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/pull.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'zip'
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Pull < Base
+      Options = Data.define(:dir, :quiet, :id, :force)
+
+      def call
+        context.validate!
+        authenticate!
+
+        plugin_settings_id = options.id || config.plugin.id
+        raise PluginIdRequired, 'plugin ID must be specified' if plugin_settings_id.nil?
+
+        unless options.force
+          answer = prompt('Local plugin files will be overwritten. Are you sure? (y/n) ').downcase
+          raise Aborted, 'aborting' unless %w[y yes].include?(answer)
+        end
+
+        api = APIClient.new(config)
+        tempfile = api.get_plugin_setting_archive(plugin_settings_id)
+        size = 0
+
+        begin
+          Zip::File.open(tempfile.path) do |zip_file|
+            zip_file.each do |entry|
+              dest_path = paths.src_dir.join(entry.name)
+              dest_path.dirname.mkpath
+              # NOTE: delete-before-extract avoids EACCES on Linux when an
+              # existing template-generated file is non-writable.
+              # rubyzip's block-based overwrite confirmation does not chmod.
+              dest_path.delete if dest_path.exist?
+              zip_file.extract(entry, destination_directory: paths.src_dir)
+            end
+          end
+
+          size = File.size(tempfile.path)
+        ensure
+          tempfile.close
+        end
+
+        reporter.info "Downloaded plugin (#{size} bytes)"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/push.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tmpdir'
+require 'zip'
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Push < Base
+      Options = Data.define(:dir, :quiet, :id, :force)
+
+      # Build the archive under the system temp dir, not the working
+      # directory — a relative path would litter the user's project (or the
+      # repo root, in specs) if a run is interrupted before the ensure-cleanup.
+      ZIP_PATH = File.join(Dir.tmpdir, "trmnlp-upload-#{Process.pid}.zip").freeze
+
+      def call
+        context.validate!
+        authenticate!
+
+        is_new = false
+
+        api = APIClient.new(config)
+
+        plugin_settings_id = options.id || config.plugin.id
+        if plugin_settings_id.nil?
+          reporter.info 'Creating a new plugin on the server...'
+          response = api.post_plugin_setting(name: 'New TRMNLP Plugin', plugin_id: 37) # hardcoded id for private_plugin
+          plugin_settings_id = response.dig('data', 'id')
+          is_new = true
+        end
+
+        unless is_new || options.force
+          answer = prompt('Plugin settings on the server will be overwritten. Are you sure? (y/n) ').downcase
+          raise Aborted, 'aborting' unless %w[y yes].include?(answer)
+        end
+
+        Zip::File.open(ZIP_PATH, create: true) do |zip_file|
+          paths.src_files.each do |file|
+            zip_file.add(File.basename(file), file)
+          end
+        end
+
+        response = api.post_plugin_setting_archive(plugin_settings_id, ZIP_PATH)
+        paths.plugin_config.write(response.dig('data', 'settings_yaml'))
+
+        size = File.size(ZIP_PATH)
+
+        reporter.info <<~HEREDOC
+          Uploaded plugin (#{size} bytes)
+          Dashboard: #{config.app.edit_plugin_settings_uri(plugin_settings_id)}
+        HEREDOC
+
+        if is_new
+          reporter.info <<~HEREDOC
+
+            IMPORTANT! Don't forget to add it to your device playlist!
+
+                #{config.app.playlists_uri}
+          HEREDOC
+        end
+      rescue StandardError
+        if is_new && plugin_settings_id
+          reporter.info 'Error during creation, cleaning up...'
+          api.delete_plugin_setting(plugin_settings_id)
+        end
+
+        raise
+      ensure
+        FileUtils.rm_f(ZIP_PATH)
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/serve.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+
+require_relative 'base'
+require_relative '../api_client'
+require_relative '../browser_pool'
+
+module TRMNLP
+  module Commands
+    class Serve < Base
+      Options = Data.define(:dir, :quiet, :bind, :port)
+
+      def call
+        context.validate!
+        report_form_field_warnings
+
+        # Must come AFTER parsing options
+        require_relative '../app'
+
+        # Now we can configure things
+        App.set(:context, context)
+        App.set(:browser_pool, BrowserPool.new(driver_factory: method(:build_firefox_driver)))
+        App.set(:bind, options.bind)
+        App.set(:port, options.port)
+        permit_all_hosts if codespaces?
+
+        # Finally, start the app!
+        App.run!
+      end
+
+      private
+
+      # Codespaces forwards the dev port through a proxy whose Host header Sinatra rejects.
+      def codespaces? = ENV['CODESPACES'] == 'true'
+
+      def permit_all_hosts
+        App.set(:host_authorization, { allow_if: ->(_env) { true } })
+      end
+
+      def build_firefox_driver
+        options = Selenium::WebDriver::Firefox::Options.new
+        options.add_argument('--headless')
+        options.add_argument('--disable-web-security')
+        # Disable subpixel antialiasing — its colour fringing quantizes badly on 1-bit e-ink.
+        options.add_preference('gfx.text.disable-aa', true)
+        options.add_preference('gfx.text.subpixel-position.force-disabled', true)
+        Selenium::WebDriver.for(:firefox, options: options).tap do |driver|
+          driver.manage.window.maximize
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/commands.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+Dir[File.join(__dir__, 'commands', '*.rb')].each { |file| require file }

data/lib/trmnlp/config/app.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module TRMNLP
+  class Config
+    # Stores trmnlp-wide configuration (irrespective of the current plugin)
+    class App
+      def initialize(paths)
+        @paths = paths
+        @config = read_config
+      end
+
+      def save
+        paths.app_config_dir.mkpath
+        paths.app_config.write(YAML.dump(@config))
+      end
+
+      def logged_in? = api_key && !api_key.empty?
+      def logged_out? = !logged_in?
+
+      def api_key
+        env_api_key = ENV.fetch('TRMNL_API_KEY', nil)
+        return env_api_key if env_api_key && !env_api_key.empty?
+
+        @config['api_key']
+      end
+
+      def api_key=(key)
+        @config['api_key'] = key
+      end
+
+      def base_uri = URI.parse(@config['base_url'] || 'https://trmnl.com')
+
+      def api_uri = URI.join(base_uri, '/api')
+
+      def account_uri = URI.join(base_uri, '/account')
+
+      def edit_plugin_settings_uri(id) = URI.join(base_uri, "/plugin_settings/#{id}/edit")
+
+      def playlists_uri = URI.join(base_uri, '/playlists')
+
+      private
+
+      attr_reader :paths
+
+      def read_config = paths.app_config.exist? ? YAML.safe_load(paths.app_config.read) : {}
+    end
+  end
+end

data/lib/trmnlp/config/plugin.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'yaml'
+
+require_relative '../errors'
+require_relative '../framework_version'
+
+module TRMNLP
+  class Config
+    class Plugin
+      def initialize(paths, project_config)
+        @paths = paths
+        @project_config = project_config
+        reload!
+      end
+
+      def reload!
+        @config = if paths.plugin_config.exist?
+                    YAML.safe_load_file(paths.plugin_config, permitted_classes: [Date, Time]) || {}
+                  else
+                    {}
+                  end
+      rescue Psych::SyntaxError => e
+        raise InvalidConfig, "settings.yml is not valid YAML: #{e.message}"
+      end
+
+      def strategy = @config['strategy']
+      def polling? = strategy == 'polling'
+      def webhook? = strategy == 'webhook'
+      def static? = strategy == 'static'
+
+      def polling_urls
+        # 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")
+      end
+
+      # for {{ trmnl }}
+      def polling_url_text = polling_urls.join("\r\n")
+
+      def polling_verb = @config['polling_verb'] || 'GET'
+
+      def polling_headers
+        # 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'] || '')
+        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 dark_mode = @config['dark_mode'] || 'no'
+
+      def no_screen_padding = @config['no_screen_padding'] || 'no'
+
+      def id = @config['id']
+
+      def static_data
+        JSON.parse(@config['static_data'] || '{}')
+      rescue JSON::ParserError
+        raise InvalidConfig, 'invalid JSON in static_data'
+      end
+
+      # Explicit language for transform.* code. If absent, the language
+      # is inferred from the file extension by Paths#transform_file.
+      # This one lives on the plugin (settings.yml) because production
+      # stores it on the plugin_setting record.
+      def serverless_language = @config['serverless_language']
+
+      # The TRMNL design-system version this plugin renders against.
+      # Lives on the plugin (settings.yml), like serverless_language,
+      # because production stores it on the plugin_setting record — so it
+      # round-trips through `trmnlp push` / `pull`. Accepts 'latest'
+      # (default), a pinned version, or nil (treated as latest). See
+      # db/data/framework_versions.yml for the supported set.
+      def framework_version
+        FrameworkVersion.new(@config['framework_version'], asset_host: project_config.asset_host)
+      rescue ArgumentError => e
+        raise InvalidConfig, e.message
+      end
+
+      # The custom-field *definitions* declared in settings.yml — the list
+      # of field hashes (keyname/name/field_type/...). Distinct from
+      # Config::Project#custom_fields, which holds the field *values*.
+      def custom_field_definitions = @config['custom_fields'] || []
+
+      # The raw parsed settings.yml hash. Most callers want the semantic
+      # readers above; `trmnlp lint` needs the uninterpreted values because
+      # it searches the raw {{ }} templates the semantic readers render away.
+      def settings = @config
+
+      private
+
+      attr_reader :paths, :project_config
+
+      def with_custom_fields(value) = project_config.with_custom_fields(value)
+
+      def string_to_hash(str, delimiter: '=')
+        str.split('&').map do |k_v|
+          key, value = k_v.split(delimiter)
+          next if value.nil?
+
+          { key => CGI.unescape_uri_component(value) }
+        end.compact.reduce({}, :merge)
+      end
+    end
+  end
+end

data/lib/trmnlp/config/project.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'trmnl/liquid'
+require 'yaml'
+
+require_relative '../errors'
+require_relative '../framework_version'
+
+module TRMNLP
+  class Config
+    class Project
+      attr_reader :paths
+
+      def initialize(paths)
+        @paths = paths
+        reload!
+      end
+
+      def reload!
+        @config = if paths.trmnlp_config.exist?
+                    YAML.safe_load_file(paths.trmnlp_config, permitted_classes: [Date, Time]) || {}
+                  else
+                    {}
+                  end
+      rescue Psych::SyntaxError => e
+        raise InvalidConfig, ".trmnlp.yml is not valid YAML: #{e.message}"
+      end
+
+      def user_filters = @config['custom_filters'] || []
+
+      def live_render? = !watch_paths.empty?
+
+      def watch_paths
+        (@config['watch'] || []).map { |watch_path| paths.expand(watch_path) }.uniq
+      end
+
+      def custom_fields = @config.fetch('custom_fields', {}).transform_values { |v| stringify_field_value(v) }
+
+      def user_data_overrides = @config['variables'] || {}
+
+      # for interpolating custom_fields into polling_* options
+      def with_custom_fields(value)
+        custom_fields_with_env = custom_fields.transform_values { |v| with_env(v) }
+        parse_liquid(value).render(custom_fields_with_env)
+      end
+
+      def time_zone = @config['time_zone'] || 'UTC'
+
+      # Local override for the framework asset host (offline / mirrored
+      # dev). Trmnlp-specific (local dev only) — so it stays in
+      # .trmnlp.yml. Consumed by Config::Plugin#framework_version.
+      def asset_host = @config['framework_asset_host'] || FrameworkVersion::DEFAULT_ASSET_HOST
+
+      # Toggles serverless transform support. Enabled by default; set to
+      # 'disabled' in .trmnlp.yml to turn it off. A transform only runs
+      # when a src/transform.* file is also present, so the default is
+      # inert until the plugin actually ships one. Transforms run
+      # in-process via the bundled python/node/php/ruby interpreters; set
+      # serverless_daemon_url to route to a remote transform daemon
+      # instead. Lives in .trmnlp.yml because this is purely a
+      # local-dev decision.
+      def transform_runtime = @config['transform_runtime'] || 'enabled'
+
+      # Opt-in URL of a remote transform daemon. When set, transforms
+      # POST here instead of running locally — useful for
+      # production-fidelity testing or shared team daemons.
+      def serverless_daemon_url = @config['serverless_daemon_url']
+
+      # Bearer token for the remote transform daemon. Mirrors Config::App's
+      # ENV-first pattern so the secret stays out of version control —
+      # $TRMNL_SERVERLESS_DAEMON_API_KEY takes priority, falls through to
+      # the .trmnlp.yml key if no env var is set.
+      def serverless_daemon_api_key
+        env_key = ENV.fetch('TRMNL_SERVERLESS_DAEMON_API_KEY', nil)
+        return env_key if env_key && !env_key.empty?
+
+        @config['serverless_daemon_api_key']
+      end
+
+      private
+
+      # NOTE: arrays (multi-select fields) and hashes are preserved as-is;
+      # only their leaf values are stringified to match production
+      # behavior.
+      def stringify_field_value(value)
+        case value
+        when Array then value.map(&:to_s)
+        when Hash then value.transform_values { |v| stringify_field_value(v) }
+        else value.to_s
+        end
+      end
+
+      # for interpolating ENV vars into custom_fields
+      def with_env(value)
+        return value.map { |v| with_env(v) } if value.is_a?(Array)
+        return value.transform_values { |v| with_env(v) } if value.is_a?(Hash)
+
+        parse_liquid(value).render({ 'env' => ENV.to_h })
+      end
+
+      def parse_liquid(contents)
+        Liquid::Template.parse(contents, environment: TRMNL::Liquid.new)
+      end
+    end
+  end
+end

data/lib/trmnlp/config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'config/app'
+require_relative 'config/plugin'
+require_relative 'config/project'
+
+module TRMNLP
+  class Config
+    attr_reader :app, :project, :plugin
+
+    def initialize(path)
+      @app = App.new(path)
+      @project = Project.new(path)
+      @plugin = Plugin.new(path, @project)
+    end
+  end
+end

data/lib/trmnlp/context.rb

@@ -0,0 +1,35 @@
+# 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, :reporter
+
+    def initialize(root_dir, reporter: Reporter.new)
+      @paths = Paths.new(root_dir)
+      @config = Config.new(paths)
+      @reporter = reporter
+    end
+
+    # 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:)
+
+    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