trmnl_preview 0.3.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e965687c88e23b15e8727f9b871b6a2529bc28c388fa2e8733fb5034915ec405
-  data.tar.gz: c1299d3ce7b27a13be79d0018535c8f1b64171f7154d9dd1f425eeacbcbc0129
+  metadata.gz: 9cee09b6deb0fc063e5358d6d636536513dc31cba86f0fe4e71ee4d2e1d3a7a5
+  data.tar.gz: 7b421d7ae1ace73b2e7370191e853946a857278f4f17332ace859bcf9581822a
 SHA512:
-  metadata.gz: d507258ba8a315daae87b83dc5609f2aa99c9d1c674f7067cd2b67b84382a4746c8f299c7c3d0e3e9cc4f378846ca3f5696f4aa8f1dcb65c6eec8b6e44f46d74
-  data.tar.gz: 02231d9584b0b24a4b7b2749c85cbf14af2c3b6d5321c63dc03bf6e8bb7655b03ee37d86ba69b7ac16ebb3acb367cad2bf54ec437e405a1a842eb1f9263090f3
+  metadata.gz: 5d97a1e0f9c461796aa141b88d7c4c2826e2693764c5cdba9013260162b9dad16220b47bd49b36b2f8cbbaeb2c985d1851f3780b33326bd9f518f1d9604774eb
+  data.tar.gz: 16a38e4c92c20db294e80e6c729a3e7f12cdf5667785d80baabeb4ab93720a56b02a3346cb6efdae01d5d715b1919eab1d7fb4f34f40ffee2c7e96ce80158a69

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.5.1
+
+- Fixed `trmnl init`
+
+## 0.5.0
+
+- Added `trmlnp init` command
+- Added `trmnlp clone` command
+- Improved `trmnlp push` to create remote plugin on first publish
+- Changed syntax of `trmnlp push` and `trmnlp pull` commands
+- Added `oj` gem for JSON parsing (#32)
+
+## 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

@@ -8,33 +8,50 @@ The server watches the filesystem for changes to the Liquid templates, seamlessl
 
 ![Screenshot](docs/preview.png)
 
-## Creating a Plugin
+## Project Structure
 
-This is the structure of a plugin repository.
+This is the structure of a plugin project:
 
 ```
-views/
-    full.liquid
-    half_horizontal.liquid
-    half_vertical.liquid
-    quadrant.liquid
-config.toml
+.
+├── .trmnlp.yml
+├── bin
+│   └── dev
+└── src
+    ├── full.liquid
+    ├── half_horizontal.liquid
+    ├── half_vertical.liquid
+    ├── quadrant.liquid
+    └── settings.yml
 ```
 
-See [config.example.toml](config.example.toml) for an example config.
+## Creating a New Plugin
 
-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.
+You can start building a plugin locally, then `push` it to the TRMNL server for display on your device.
 
-## Running the Server (Docker)
+```sh
+trmnlp init my_plugin  # generate
+cd my_plugin
+trmnlp serve           # develop locally
+trmnlp login           # authenticate
+trmnlp push            # upload
+```
+
+## Modifying an Existing Plugin
+
+If you have built a plugin with the web-based editor, you can `clone` it, work on it locally, and `push` changes back to the server.
 
 ```sh
-docker run \
-    -p 4567:4567 \
-    -v /path/to/plugin/on/host:/plugin \
-    schrockwell/trmnlp
+trmnlp login                 # authenticate
+trmnlp clone my_plugin [id]  # first download
+cd my_plugin
+trmnlp serve                 # develop locally
+trmnlp push                  # upload
 ```
 
-## Running the Server (Local Ruby)
+## Running trmnlp
+
+### Via RubyGems
 
 Prerequisites:
 
@@ -43,29 +60,59 @@ Prerequisites:
   - Firefox
   - ImageMagick
 
-In the plugin repository:
-
 ```sh
 gem install trmnl_preview
-trmnlp serve                # Starts the server
+trmnlp serve
 ```
 
-## Usage Notes
+### Via Docker (`trmnlp serve` only)
 
-When the strategy is "polling", the specified URL will be fetched once, when the server starts.
+```sh
+docker run \
+    -p 4567:4567 \
+    -v /path/to/plugin/on/host:/plugin \
+    trmnl/trmnlp
+```
+
+## `.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.
+
+```yaml
+---
+# 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 }}" # interpolate $IACO environment variable
+
+# 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,72 @@
+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
+        JSON.parse(response.body)
+      else
+        raise Error, "failed to upload plugin settings archive: #{response.status} #{response.body}"
+      end
+    end
+
+    def post_plugin_setting(params)
+      response = conn.post("plugin_settings", params.to_json, content_type: 'application/json')
+
+      if response.status == 200
+        JSON.parse(response.body)
+      else
+        raise Error, "failed to create plugin setting: #{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,66 @@
+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
+
+    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 '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)
+    end
+
+    desc 'clone NAME ID', 'Copy a plugin project from TRMNL server'
+    def clone(name, id)
+      Commands::Clone.new(options).call(name, id)
+    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.new(options).call
+    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.new(options).call
+    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,40 @@
+require 'thor/core_ext/hash_with_indifferent_access'
+
+require_relative '../context'
+
+module TRMNLP
+  module Commands
+    class Base
+      include Thor::CoreExt
+
+      def initialize(options = HashWithIndifferentAccess.new)
+        @options = HashWithIndifferentAccess.new(options)
+        @context = Context.new(@options.dir)
+      end
+
+      def call
+        raise NotImplementedError
+      end
+
+      protected
+
+      attr_accessor :options, :context
+
+      def config = context.config
+      def paths = context.paths
+
+      def authenticate!
+        raise Error, "please run `trmnlp login`" unless config.app.logged_in?
+      end
+
+      def output(message)
+        puts(message) unless options.quiet?
+      end
+
+      def prompt(message)
+        print message
+        $stdin.gets.chomp
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/build.rb

@@ -0,0 +1,21 @@
+require_relative 'base'
+
+module TRMNLP
+  module Commands
+    class Build < Base
+      def call
+        context.validate!
+        context.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!"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/clone.rb

@@ -0,0 +1,30 @@
+require_relative 'base'
+require_relative 'pull'
+
+module TRMNLP
+  module Commands
+    class Clone < Base
+      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?
+
+        Init.new(dir: options.dir, skip_liquid: true, quiet: true).call(directory_name)
+
+        Pull.new(dir: destination_path.to_s, force: true, id: id).call
+
+        output <<~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,55 @@
+require 'fileutils'
+
+require_relative 'base'
+
+module TRMNLP
+  module Commands
+    class Init < Base
+      def call(name)
+        destination_dir = Pathname.new(options.dir).join(name)
+
+        unless destination_dir.exist?
+          output "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'
+              output "Skipping #{destination_pathname}"
+              next
+            end
+          end
+
+          output "Creating #{destination_pathname}"
+          FileUtils.cp(source_pathname, destination_pathname)
+        end
+
+        output <<~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/login.rb

@@ -0,0 +1,24 @@
+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)
+          output "Currently authenticated as: #{anonymous_key}" 
+        end
+
+        output "Please visit #{config.app.account_uri} to grab your API key, then paste it here."
+        
+        api_key = prompt("API Key: ")
+        raise Error, "API key cannot be empty" if api_key.empty?
+        
+        config.app.api_key = api_key
+        config.app.save
+        
+        output "Saved changes to #{paths.app_config}"
+      end
+    end
+  end
+end

data/lib/trmnlp/commands/pull.rb

@@ -0,0 +1,43 @@
+require 'zip'
+
+require_relative 'base'
+require_relative '../api_client'
+
+module TRMNLP
+  module Commands
+    class Pull < Base
+      def call
+        context.validate!
+        authenticate!
+
+        plugin_settings_id = options.id || config.plugin.id
+        raise Error, '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 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