trmnl_preview 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e965687c88e23b15e8727f9b871b6a2529bc28c388fa2e8733fb5034915ec405
-  data.tar.gz: c1299d3ce7b27a13be79d0018535c8f1b64171f7154d9dd1f425eeacbcbc0129
+  metadata.gz: 51839346d4b2bd24698655d8e6a86a1a93aac73d2882a5b907072db9851ffa03
+  data.tar.gz: 0e54398757e865c8907f3b65b4046519dba2dced17d6d62ce3342b89ce2a5d75
 SHA512:
-  metadata.gz: d507258ba8a315daae87b83dc5609f2aa99c9d1c674f7067cd2b67b84382a4746c8f299c7c3d0e3e9cc4f378846ca3f5696f4aa8f1dcb65c6eec8b6e44f46d74
-  data.tar.gz: 02231d9584b0b24a4b7b2749c85cbf14af2c3b6d5321c63dc03bf6e8bb7655b03ee37d86ba69b7ac16ebb3acb367cad2bf54ec437e405a1a842eb1f9263090f3
+  metadata.gz: 2e17bf9dba3a94a153c0182493d7b2ee597ba70b54177793fedae27a154817de8a79eb108a50194b5b5e0f1d2c012ff0b9047b9457cbdf52ad9b5e4d6331c6ab
+  data.tar.gz: a66a9b16b7c3512d018bd10a2444a7cfa4ecf335e9fd580583f27ac4cf6030c810bd48ab20878e3ec704b8f0faf64b7bc6e28ad08e585d1bf51ea3a01d0575fb

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.4.0
+
+### Plugin Migration Strategy
+
+The plugin directory structure has changed to better align with the [plugin archive format](https://help.usetrmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0). 
+
+Here is a migration strategy for existing plugin repositories:
+
+1. Create `.trmnlp.yml` and bring over preview settings from `config.toml` - [see README](README.md)
+2. Rename directory `views/` to `src/`
+3. Create `src/settings.yml` and bring over plugin settings from `config.toml` - [see TRMNL docs](https://help.usetrmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0)
+4. Delete `config.toml`
+
+### Changes
+
+- Change plugin directory structure (see README for details)
+- Add `login`, `push`, and `pull` commands
+- Bring up-to-date with latest private plugin features:
+  - Add `static` strategy
+  - Add polling features: multiple URLs, new verbs, and request body
+  - Add settings `dark_mode`, `no_screen_padding`, `custom_fields`
+  - Add interpolation of custom fields in `polling\_\*` options
+  - Add `{{ trmnl }}` variables 
+- Add `watch` config
+- Add interpolation of environment variables in `.trmnlp.yml` via `{{ env }}`
+- Add auto-reload when `.trmnlp.yml` or `settings.yml` changes
+- Add variable display
+- Fix crash when #poll_data fails (#12)
+- Fix git runtime error in Docker container (#12)
+
+
+
 ## 0.3.2
 
 - Add bitmap rendering

data/README.md

@@ -10,20 +10,25 @@ The server watches the filesystem for changes to the Liquid templates, seamlessl
 
 ## Creating a Plugin
 
-This is the structure of a plugin repository.
+This is the structure of a plugin project.
 
 ```
-views/
+.trmnlp.yml
+src/
     full.liquid
     half_horizontal.liquid
     half_vertical.liquid
     quadrant.liquid
-config.toml
+    settings.yml
 ```
 
-See [config.example.toml](config.example.toml) for an example config.
+## Syncing Plugin With TRMNL Server
 
-The [trmnl-hello](https://github.com/schrockwell/trmnl-hello) repository is provided as a jumping-off point for creating new plugins. Simply fork the repo, clone it, and start hacking.
+```sh
+trmnl login      # authenticate with TRMNL account
+trmnl pull [id]  # download (plugin ID required on first pull only)
+trmnl push       # upload
+```
 
 ## Running the Server (Docker)
 
@@ -31,7 +36,7 @@ The [trmnl-hello](https://github.com/schrockwell/trmnl-hello) repository is prov
 docker run \
     -p 4567:4567 \
     -v /path/to/plugin/on/host:/plugin \
-    schrockwell/trmnlp
+    trmnl/trmnlp
 ```
 
 ## Running the Server (Local Ruby)
@@ -43,29 +48,53 @@ Prerequisites:
   - Firefox
   - ImageMagick
 
-In the plugin repository:
+In the plugin project:
 
 ```sh
 gem install trmnl_preview
-trmnlp serve                # Starts the server
+trmnlp serve
 ```
 
-## Usage Notes
+## `./.trmnlp.yml` Reference (Project Config)
+
+The `.trmnlp.yml` file lives in the root of the plugin project, and is for configuring the local dev server.
+
+System environment variables are made available in the `{{ env }}` Liquid varible in this file only. This can be used to safely
+supply plugin secrets, like API keys.
+
+All fields are optional.
 
-When the strategy is "polling", the specified URL will be fetched once, when the server starts.
+```yaml
+# {{ env.VARIABLE }} interpolation is available here
+---
+# auto-reload when files change (`watch: false` to disable)
+watch:
+  - src
+  - .trmnlp.yml
+
+# values of custom fields (defined in src/settings.yml)
+custom_fields:
+  station: "{{ env.ICAO }}"
+
+# override variables
+variables:
+  trmnl:
+    user:
+      name: Peter Quill
+    plugin_settings:
+      instance_name: Kevin Bacon Facts
+
+```
 
-When the strategy is "webhook", payloads can be POSTed to the `/webhook` endpoint. They are saved to `tmp/data.json` for future renders.
+## `./src/settings.yml` Reference (Plugin Config)
 
-## `config.toml` Reference
+The `settings.yml` file is part of the plugin definition. 
 
-- `strategy` - Either "polling" or "webhook"
-- `url` - The URL from which to fetch JSON data (polling strategy only)
-- `live_render` - Set to `false` to disable automatic rendering when Liquid templates change (default `true`)
-- `[polling_headers]` - A section of headers to append to the HTTP poll request (polling strategy only)
+See [TRMNL documentation](https://help.usetrmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0) for details on this file's contents.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/schrockwell/trmnl_preview.
+Bug reports and pull requests are welcome on GitHub at https://github.com/usetrmnl/trmnlp.
 
 ## License
 

data/bin/trmnlp

@@ -0,0 +1,14 @@
+#! /usr/bin/env ruby
+
+require "thor"
+
+require_relative '../lib/trmnlp/cli'
+
+begin
+  TRMNLP::CLI.start
+rescue TRMNLP::Error => e
+  puts "Error: #{e.message}"
+  exit 1
+rescue Interrupt
+  exit 1
+end

data/lib/trmnlp/api_client.rb

@@ -0,0 +1,62 @@
+require 'faraday'
+require 'faraday/multipart'
+
+require_relative 'config'
+
+module TRMNLP
+  class APIClient
+    def initialize(config)
+      @config = config
+    end
+
+    def get_plugin_setting_archive(id)
+      response = conn.get("plugin_settings/#{id}/archive")
+
+      if response.status == 200
+        temp_file = Tempfile.new(["plugin_settings_#{id}", '.zip'])
+        temp_file.binmode
+        temp_file.write(response.body)
+        temp_file.rewind
+
+        # return the path to the temp file
+        Pathname.new(temp_file.path)
+      else
+        raise Error, "failed to download plugin settings archive: #{response.status} #{response.body}"
+      end
+    end
+
+    def post_plugin_setting_archive(id, path)
+      payload = {
+        file: Faraday::Multipart::FilePart.new(path, 'application/zip')
+      }
+
+      response = conn.post("plugin_settings/#{id}/archive", payload)
+
+      if response.status == 200
+        true
+      else
+        raise Error, "failed to upload plugin settings archive: #{response.status} #{response.body}"
+      end
+    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/{trmnl_preview → trmnlp}/app.rb

@@ -6,7 +6,7 @@ require 'sinatra/base'
 require_relative 'context'
 require_relative 'screen_generator'
 
-module TRMNLPreview
+module TRMNLP
   class App < Sinatra::Base
     # Sinatra settings
     set :views, File.join(File.dirname(__FILE__), '..', '..', 'web', 'views')
@@ -15,25 +15,28 @@ module TRMNLPreview
     def initialize(*args)
       super
 
-      begin
-        @context = Context.new(settings.user_dir)
-      rescue StandardError => e
-        puts e.message
-        exit 1
-      end
+      @context = settings.context
+
+      @context.poll_data
 
-      @context.poll_data if @context.strategy == 'polling'
+      @context.start_filewatcher if @context.config.project.live_render?
 
       @live_reload_clients = []
-      @context.on_view_change do |view|
+      @context.on_view_change do |view, user_data|
         @live_reload_clients.each do |ws|
-          ws.send('reload')
+          payload = {
+            'type' => 'reload',
+            'view' => view,
+            'user_data' => user_data
+          }
+
+          ws.send(payload.to_json)
         end
       end
     end
 
     post '/webhook' do
-      @context.set_data(request.body.read)
+      @context.put_webhook(request.body.read)
       "OK"
     end
     
@@ -41,6 +44,11 @@ module TRMNLPreview
       redirect '/full'
     end
 
+    get '/data' do
+      content_type :json
+      JSON.pretty_generate(@context.user_data)
+    end
+
     get '/live_reload' do
       ws = Faye::WebSocket.new(request.env)
 
@@ -63,12 +71,16 @@ module TRMNLPreview
     VIEWS.each do |view|
       get "/#{view}" do
         @view = view
-        @live_reload = @context.live_render
+        @user_data = JSON.pretty_generate(@context.user_data)
+        @live_reload = @context.config.project.live_render?
+
         erb :index
       end
 
       get "/render/#{view}.html" do
         @view = view
+        @screen_classes = @context.screen_classes
+        
         erb :render_html do
           @context.render_template(view)
         end

data/lib/trmnlp/cli.rb

@@ -0,0 +1,51 @@
+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 directory'
+
+    def self.exit_on_failure? = true
+
+    desc 'build', 'Generate static HTML files'
+    def build
+      Commands::Build.new(options).call
+    end
+
+    desc 'login', 'Authenticate with TRMNL server'
+    def login
+      Commands::Login.new(options).call
+    end
+
+    desc 'pull [id]', 'Download plugin settings from TRMNL server'
+    method_option :force, type: :boolean, default: false, aliases: '-f',
+                  desc: 'Skip confirmation prompts'
+    def pull(plugin_settings_id = nil)
+      Commands::Pull.new(options).call(plugin_settings_id)
+    end
+
+    desc 'push [id]', 'Upload plugin settings to TRMNL server'
+    method_option :force, type: :boolean, default: false, aliases: '-f',
+                  desc: 'Skip confirmation prompts'
+    def push(plugin_settings_id = nil)
+      Commands::Push.new(options).call(plugin_settings_id)
+    end
+
+    desc 'serve', 'Start a local dev server'
+    method_option :bind, type: :string, default: '127.0.0.1', aliases: '-b', desc: 'Bind address'
+    method_option :port, type: :numeric, default: 4567, aliases: '-p', desc: 'Port number'
+    def serve
+      Commands::Serve.new(options).call
+    end
+
+    desc 'version', 'Show version'
+    def version
+      puts VERSION
+    end
+  end
+end

data/lib/trmnlp/commands/base.rb

@@ -0,0 +1,23 @@
+require_relative '../context'
+
+module TRMNLP
+  module Commands
+    class Base
+      def initialize(options)
+        @options = options
+        @context = Context.new(options.dir)
+      end
+
+      def call
+        raise NotImplementedError
+      end
+
+      private
+
+      attr_accessor :options, :context
+
+      def config = context.config
+      def paths = context.paths
+    end
+  end
+end

data/lib/trmnlp/commands/build.rb

@@ -0,0 +1,22 @@
+require_relative 'base'
+
+module TRMNLP
+  module Commands
+    class Build < Base
+      def call
+        context = Context.new(options.dir)
+        context.validate!
+        context.poll_data
+        context.paths.create_build_dir
+
+        VIEWS.each do |view|
+          output_path = context.paths.build_dir.join("#{view}.html")
+          puts "Writing #{output_path}..."
+          output_path.write(context.render_full_page(view))
+        end
+  
+        puts "Done!"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/login.rb

@@ -0,0 +1,25 @@
+require_relative 'base'
+
+module TRMNLP
+  module Commands
+    class Login < Base
+      def call
+        if config.app.logged_in?
+          anonymous_key = config.app.api_key[0..10] + '*' * (config.app.api_key.length - 11)
+          puts "Currently authenticated as: #{anonymous_key}" 
+        end
+
+        puts "Please visit #{config.app.account_uri} to grab your API key, then paste it here."
+        
+        print "API Key: "
+        api_key = STDIN.gets.chomp
+        raise Error, "API key cannot be empty" if api_key.empty?
+        
+        config.app.api_key = api_key
+        config.app.save
+        
+        puts "Saved changes to #{paths.app_config}"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/pull.rb

@@ -0,0 +1,45 @@
+require 'zip'
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Pull < Base
+      def call(plugin_settings_id)
+        context.validate!
+        
+        raise Error, "please run `trmnlp login`" unless config.app.logged_in?
+
+        plugin_settings_id ||= config.plugin.id
+        raise Error, 'plugin ID must be specified' if plugin_settings_id.nil?
+
+        unless options.force
+          print "Local plugin files will be overwritten. Are you sure? (y/n) "
+          answer = $stdin.gets.chomp.downcase
+          raise Error, 'aborting' unless answer == 'y' || answer == 'yes'
+        end
+
+        api = APIClient.new(config)
+        temp_path = api.get_plugin_setting_archive(plugin_settings_id)
+        size = 0
+
+        begin
+          Zip::File.open(temp_path) do |zip_file|
+            zip_file.each do |entry|
+              dest_path = paths.src_dir.join(entry.name)
+              dest_path.dirname.mkpath
+              zip_file.extract(entry, dest_path) { true } # overwrite existing
+            end
+          end
+
+          size = File.size(temp_path)
+        ensure
+          temp_path.delete
+        end
+
+        puts "Downloaded plugin (#{size} bytes)"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/push.rb

@@ -0,0 +1,43 @@
+require 'zip'
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Push < Base
+      def call(plugin_settings_id)
+        context.validate!
+        
+        raise Error, "please run `trmnlp login`" unless config.app.logged_in?
+
+        plugin_settings_id ||= config.plugin.id
+        raise Error, 'plugin ID must be specified' if plugin_settings_id.nil?
+
+        unless options.force
+          print "Plugin settings on the server will be overwritten. Are you sure? (y/n) "
+          answer = $stdin.gets.chomp.downcase
+          raise Error, 'aborting' unless answer == 'y' || answer == 'yes'
+        end
+
+        api = APIClient.new(config)
+        size = 0
+
+        Tempfile.create(binmode: true) do |temp_file|
+          Zip::File.open(temp_file.path, Zip::File::CREATE) do |zip_file|
+            paths.src_files.each do |file|
+              zip_file.add(File.basename(file), file)
+            end
+          end
+        
+          api.post_plugin_setting_archive(plugin_settings_id, temp_file.path)
+
+          size = File.size(temp_file.path)
+        end
+        
+
+        puts "Uploaded plugin (#{size} bytes)"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/serve.rb

@@ -0,0 +1,25 @@
+require 'zip'
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Serve < Base
+      def call
+        context.validate!
+        
+        # Must come AFTER parsing options
+        require_relative '../app'
+
+        # Now we can configure things
+        App.set(:context, context)
+        App.set(:bind, options.bind)
+        App.set(:port, options.port)
+
+        # Finally, start the app!
+        App.run!
+      end
+    end
+  end
+end

data/lib/trmnlp/commands.rb

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

data/lib/trmnlp/config/app.rb

@@ -0,0 +1,39 @@
+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 = @config['api_key']
+
+      def api_key=(key)
+        @config['api_key'] = key
+      end
+
+      def base_uri = URI.parse(@config['base_url'] || 'https://usetrmnl.com')
+
+      def api_uri = URI.join(base_uri, 'api')
+
+      def account_uri = URI.join(base_uri, 'account')
+
+      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,74 @@
+require 'yaml'
+
+module TRMNLP
+  class Config
+    class Plugin
+      def initialize(paths, trmnlp_config)
+        @paths = paths
+        @trmnlp_config = trmnlp_config
+        reload!
+      end
+
+      def reload!
+        if paths.plugin_config.exist?
+          @config = YAML.load_file(paths.plugin_config)
+        else
+          @config = {}
+        end
+      end
+      
+      def strategy = @config['strategy']
+      def polling? = strategy == 'polling'
+      def webhook? = strategy == 'webhook'
+      def static? = strategy == 'static'
+
+      def polling_urls
+        return [] if @config['polling_url'].nil? || @config['polling_url'].empty?
+
+        urls = @config['polling_url'].split("\n").map(&:strip)
+
+        urls.map { |url| with_custom_fields(url) }
+      end
+
+      def polling_url_text = polling_urls.join("\r\n") # for {{ trmnl }}
+
+      def polling_verb = @config['polling_verb'] || 'GET'
+
+      def polling_headers
+        string_to_hash(@config['polling_headers'] || '').transform_values { |v| with_custom_fields(v) }
+      end
+
+      def polling_headers_encoded = polling_headers.map { |k, v| "#{k}=#{v}" }.join('&') # for {{ trmnl }}
+
+      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 Error, 'invalid JSON in static_data'
+      end
+
+      private
+
+      attr_reader :paths, :trmnlp_config
+
+      def with_custom_fields(value) = trmnlp_config.with_custom_fields(value)
+
+      # copied from TRMNL core
+      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