trmnl_preview 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51839346d4b2bd24698655d8e6a86a1a93aac73d2882a5b907072db9851ffa03
-  data.tar.gz: 0e54398757e865c8907f3b65b4046519dba2dced17d6d62ce3342b89ce2a5d75
+  metadata.gz: 9cee09b6deb0fc063e5358d6d636536513dc31cba86f0fe4e71ee4d2e1d3a7a5
+  data.tar.gz: 7b421d7ae1ace73b2e7370191e853946a857278f4f17332ace859bcf9581822a
 SHA512:
-  metadata.gz: 2e17bf9dba3a94a153c0182493d7b2ee597ba70b54177793fedae27a154817de8a79eb108a50194b5b5e0f1d2c012ff0b9047b9457cbdf52ad9b5e4d6331c6ab
-  data.tar.gz: a66a9b16b7c3512d018bd10a2444a7cfa4ecf335e9fd580583f27ac4cf6030c810bd48ab20878e3ec704b8f0faf64b7bc6e28ad08e585d1bf51ea3a01d0575fb
+  metadata.gz: 5d97a1e0f9c461796aa141b88d7c4c2826e2693764c5cdba9013260162b9dad16220b47bd49b36b2f8cbbaeb2c985d1851f3780b33326bd9f518f1d9604774eb
+  data.tar.gz: 16a38e4c92c20db294e80e6c729a3e7f12cdf5667785d80baabeb4ab93720a56b02a3346cb6efdae01d5d715b1919eab1d7fb4f34f40ffee2c7e96ce80158a69

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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

data/README.md

@@ -8,38 +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 project.
+This is the structure of a plugin project:
 
 ```
-.trmnlp.yml
-src/
-    full.liquid
-    half_horizontal.liquid
-    half_vertical.liquid
-    quadrant.liquid
-    settings.yml
+.
+├── .trmnlp.yml
+├── bin
+│   └── dev
+└── src
+    ├── full.liquid
+    ├── half_horizontal.liquid
+    ├── half_vertical.liquid
+    ├── quadrant.liquid
+    └── settings.yml
 ```
 
-## Syncing Plugin With TRMNL Server
+## Creating a New Plugin
+
+You can start building a plugin locally, then `push` it to the TRMNL server for display on your device.
 
 ```sh
-trmnl login      # authenticate with TRMNL account
-trmnl pull [id]  # download (plugin ID required on first pull only)
-trmnl push       # upload
+trmnlp init my_plugin  # generate
+cd my_plugin
+trmnlp serve           # develop locally
+trmnlp login           # authenticate
+trmnlp push            # upload
 ```
 
-## Running the Server (Docker)
+## 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 \
-    trmnl/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:
 
@@ -48,14 +60,21 @@ Prerequisites:
   - Firefox
   - ImageMagick
 
-In the plugin project:
-
 ```sh
 gem install trmnl_preview
 trmnlp serve
 ```
 
-## `./.trmnlp.yml` Reference (Project Config)
+### Via Docker (`trmnlp serve` only)
+
+```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.
 
@@ -65,7 +84,6 @@ supply plugin secrets, like API keys.
 All fields are optional.
 
 ```yaml
-# {{ env.VARIABLE }} interpolation is available here
 ---
 # auto-reload when files change (`watch: false` to disable)
 watch:
@@ -74,7 +92,7 @@ watch:
 
 # values of custom fields (defined in src/settings.yml)
 custom_fields:
-  station: "{{ env.ICAO }}"
+  station: "{{ env.ICAO }}" # interpolate $IACO environment variable
 
 # override variables
 variables:
@@ -86,7 +104,7 @@ variables:
 
 ```
 
-## `./src/settings.yml` Reference (Plugin Config)
+## `src/settings.yml` Reference (Plugin Config)
 
 The `settings.yml` file is part of the plugin definition. 
 

data/lib/trmnlp/api_client.rb

@@ -33,12 +33,22 @@ module TRMNLP
       response = conn.post("plugin_settings/#{id}/archive", payload)
 
       if response.status == 200
-        true
+        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

data/lib/trmnlp/cli.rb

@@ -8,7 +8,9 @@ module TRMNLP
     package_name 'trmnlp'
 
     class_option :dir, type: :string, default: Dir.pwd, aliases: '-d',
-                  desc: 'Plugin directory'
+                  desc: 'Plugin project directory'
+
+    class_option :quiet, type: :boolean, default: false, desc: 'Suppress output', aliases: '-q'
 
     def self.exit_on_failure? = true
 
@@ -22,18 +24,31 @@ module TRMNLP
       Commands::Login.new(options).call
     end
 
-    desc 'pull [id]', 'Download plugin settings from TRMNL server'
+    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'
-    def pull(plugin_settings_id = nil)
-      Commands::Pull.new(options).call(plugin_settings_id)
+    method_option :id, type: :string, aliases: '-i', desc: 'Plugin settings ID'
+    def pull
+      Commands::Pull.new(options).call
     end
 
-    desc 'push [id]', 'Upload plugin settings to TRMNL server'
+    desc 'push', 'Upload latest 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)
+    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'

data/lib/trmnlp/commands/base.rb

@@ -1,23 +1,40 @@
+require 'thor/core_ext/hash_with_indifferent_access'
+
 require_relative '../context'
 
 module TRMNLP
   module Commands
     class Base
-      def initialize(options)
-        @options = options
-        @context = Context.new(options.dir)
+      include Thor::CoreExt
+
+      def initialize(options = HashWithIndifferentAccess.new)
+        @options = HashWithIndifferentAccess.new(options)
+        @context = Context.new(@options.dir)
       end
 
       def call
         raise NotImplementedError
       end
 
-      private
+      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

@@ -4,18 +4,17 @@ 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 "Writing #{output_path}..."
           output_path.write(context.render_full_page(view))
         end
   
-        puts "Done!"
+        output "Done!"
       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

@@ -6,19 +6,18 @@ module TRMNLP
       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}" 
+          output "Currently authenticated as: #{anonymous_key}" 
         end
 
-        puts "Please visit #{config.app.account_uri} to grab your API key, then paste it here."
+        output "Please visit #{config.app.account_uri} to grab your API key, then paste it here."
         
-        print "API Key: "
-        api_key = STDIN.gets.chomp
+        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
         
-        puts "Saved changes to #{paths.app_config}"
+        output "Saved changes to #{paths.app_config}"
       end
     end
   end

data/lib/trmnlp/commands/pull.rb

@@ -6,17 +6,15 @@ require_relative '../api_client'
 module TRMNLP
   module Commands
     class Pull < Base
-      def call(plugin_settings_id)
+      def call
         context.validate!
-        
-        raise Error, "please run `trmnlp login`" unless config.app.logged_in?
+        authenticate!
 
-        plugin_settings_id ||= config.plugin.id
+        plugin_settings_id = options.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
+          answer = prompt("Local plugin files will be overwritten. Are you sure? (y/n) ").downcase
           raise Error, 'aborting' unless answer == 'y' || answer == 'yes'
         end
 

data/lib/trmnlp/commands/push.rb

@@ -6,21 +6,27 @@ require_relative '../api_client'
 module TRMNLP
   module Commands
     class Push < Base
-      def call(plugin_settings_id)
+      def call
         context.validate!
-        
-        raise Error, "please run `trmnlp login`" unless config.app.logged_in?
+        authenticate!
+
+        is_new = false
 
-        plugin_settings_id ||= config.plugin.id
-        raise Error, 'plugin ID must be specified' if plugin_settings_id.nil?
+        api = APIClient.new(config)
+
+        plugin_settings_id = options.id || config.plugin.id
+        if plugin_settings_id.nil?
+          output '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 options.force
-          print "Plugin settings on the server will be overwritten. Are you sure? (y/n) "
-          answer = $stdin.gets.chomp.downcase
+        unless is_new || options.force
+          answer = prompt("Plugin settings on the server will be overwritten. Are you sure? (y/n) ").downcase
           raise Error, 'aborting' unless answer == 'y' || answer == 'yes'
         end
 
-        api = APIClient.new(config)
         size = 0
 
         Tempfile.create(binmode: true) do |temp_file|
@@ -30,13 +36,25 @@ module TRMNLP
             end
           end
         
-          api.post_plugin_setting_archive(plugin_settings_id, temp_file.path)
+          response = api.post_plugin_setting_archive(plugin_settings_id, temp_file.path)
+          paths.plugin_config.write(response.dig('data', 'settings_yaml'))
 
           size = File.size(temp_file.path)
         end
         
+        output <<~HEREDOC
+        Uploaded plugin (#{size} bytes)
+        Dashboard: #{config.app.edit_plugin_settings_uri(plugin_settings_id)}
+        HEREDOC
+
+        if is_new
+          output <<~HEREDOC
 
-        puts "Uploaded plugin (#{size} bytes)"
+          IMPORTANT! Don't forget to add it to your device playlist!
+
+              #{config.app.playlists_uri}
+          HEREDOC
+        end
       end
     end
   end

data/lib/trmnlp/config/app.rb

@@ -25,9 +25,13 @@ module TRMNLP
 
       def base_uri = URI.parse(@config['base_url'] || 'https://usetrmnl.com')
 
-      def api_uri = URI.join(base_uri, 'api')
+      def api_uri = URI.join(base_uri, '/api')
 
-      def account_uri = URI.join(base_uri, 'account')
+      def account_uri = URI.join(base_uri, '/account')
+
+      def edit_plugin_settings_uri(id) = URI.join(base_uri, "/plugin_settings/#{id.to_s}/edit")
+
+      def playlists_uri = URI.join(base_uri, '/playlists')
 
       private
 

data/lib/trmnlp/paths.rb

@@ -8,6 +8,12 @@ module TRMNLP
       @root_dir = Pathname.new(root_dir)
       @xdg = XDG.new
     end
+    
+    # --- trmnlp library ---
+    
+    def gem_dir = Pathname.new(__dir__).join('..', '..').expand_path
+
+    def templates_dir = gem_dir.join('templates')
 
     # --- directories ---
     

data/lib/trmnlp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TRMNLP
-  VERSION = "0.4.0".freeze
+  VERSION = "0.5.1".freeze
 end

data/lib/trmnlp.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module TRMNLP; end
-
+require 'oj'
+Oj.mimic_JSON()
 require_relative "trmnlp/config"
 require_relative "trmnlp/context"
 require_relative "trmnlp/version"
@@ -10,4 +11,4 @@ module TRMNLP
   VIEWS = %w{full half_horizontal half_vertical quadrant}
 
   class Error < StandardError; end
-end
+end

data/templates/init/.trmnlp.yml

@@ -0,0 +1,14 @@
+# TRMNLP configuration
+# {{ env.VARIABLE }} interpolation is available here
+---
+# auto-reload when files change (`watch: false` to disable)
+watch:
+  - .trmnlp.yml
+  - src
+
+# values of custom fields (defined in src/settings.yml)
+custom_fields: {}
+
+# override variables
+variables:
+  trmnl: {}

data/templates/init/bin/dev

@@ -0,0 +1,25 @@
+#! /bin/bash
+
+if command -v trmnlp &> /dev/null
+then
+    echo "Starting trmnlp..."
+    trmnlp serve
+    exit
+fi
+
+if command -v docker &> /dev/null
+then
+    echo "Running trmnl/trmnlp container..."
+    docker run -p 4567:4567 -v .:/plugin trmnl/trmnlp
+    exit
+fi
+
+echo "Install the trmnl_preview gem:
+
+  gem install trmnl_preview
+
+Or install Docker:
+
+    https://docs.docker.com/get-docker/"
+
+exit 1

data/templates/init/src/full.liquid

@@ -0,0 +1 @@
+full!

data/templates/init/src/half_horizontal.liquid

@@ -0,0 +1 @@
+half horizontal!

data/templates/init/src/half_vertical.liquid

@@ -0,0 +1 @@
+half vertical!

data/templates/init/src/quadrant.liquid

@@ -0,0 +1 @@
+quadrant!

data/templates/init/src/settings.yml

@@ -0,0 +1,15 @@
+#
+# Changes to this file will be overwritten by `trmnlp pull`.
+#
+# Docs: https://help.usetrmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0
+#
+---
+strategy: polling
+no_screen_padding: 'no'
+dark_mode: 'no'
+static_data: ''
+polling_verb: get
+polling_url: ''
+polling_headers: ''
+name: My Plugin
+refresh_interval: 1440

data/trmnl_preview.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |spec|
     [
       'bin/**/*',
       'lib/**/*',
+      'templates/**/{*,.*}',
       'web/**/*',
       'CHANGELOG.md',
       'LICENSE.txt',
@@ -44,7 +45,7 @@ Gem::Specification.new do |spec|
   # HTML rendering
   spec.add_dependency "liquid", "~> 5.6"
   spec.add_dependency "activesupport", "~> 8.0"
-  
+
   # BMP rendering
   spec.add_dependency "ferrum", "~> 0.16"
   spec.add_dependency 'puppeteer-ruby', '~> 0.45.6'
@@ -57,6 +58,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "xdg", "~> 9.1"
   spec.add_dependency "rubyzip", "~> 2.3.0"
   spec.add_dependency "thor", "~> 1.3"
+  spec.add_dependency "oj", "~> 3.16.9"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Rockwell Schrock
 bindir: bin
 cert_chain: []
-date: 2025-04-09 00:00:00.000000000 Z
+date: 2025-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -219,6 +219,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.16.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.16.9
 description: Automatically rebuild and preview TRNML plugins in multiple views
 email:
 - rockwell@schrock.me
@@ -238,6 +252,8 @@ files:
 - lib/trmnlp/commands.rb
 - lib/trmnlp/commands/base.rb
 - lib/trmnlp/commands/build.rb
+- lib/trmnlp/commands/clone.rb
+- lib/trmnlp/commands/init.rb
 - lib/trmnlp/commands/login.rb
 - lib/trmnlp/commands/pull.rb
 - lib/trmnlp/commands/push.rb
@@ -251,6 +267,13 @@ files:
 - lib/trmnlp/paths.rb
 - lib/trmnlp/screen_generator.rb
 - lib/trmnlp/version.rb
+- templates/init/.trmnlp.yml
+- templates/init/bin/dev
+- templates/init/src/full.liquid
+- templates/init/src/half_horizontal.liquid
+- templates/init/src/half_vertical.liquid
+- templates/init/src/quadrant.liquid
+- templates/init/src/settings.yml
 - trmnl_preview.gemspec
 - web/public/black-case.jpg
 - web/public/clear-case.jpg