trmnl_preview 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbbc567f2937e7dd1aabc75991df616728f88fa858d797384a4a63453265be5c
-  data.tar.gz: 1b1e543aa9ea1dddbb456f061f1538c22cc0edd849fc6faced3d67fa5f682677
+  metadata.gz: bdc22b090a3269c3fdbfa52287c287cbab548e6f40aa08428d037903f40dbb5b
+  data.tar.gz: 92886e598aa5e83e750bee7fdba8ee1b9d8b5f13fb6c021e2653cfa169900c44
 SHA512:
-  metadata.gz: 7b0ab9feab22239ce5e2eaa6c9b2fc7d1f889927e267c14d83eb6ec02e60a973acb9194fee59cae709ea7640c43741186788588b33e9d76ac023a5d5f09280d4
-  data.tar.gz: c18a319c45dec945b5c8f71d56c47f4478b8a82bceaed429b475cce4f57cb8a29541bcf7b1312e8fb9624513aebbd434d05c6e64f02d32322e9628cffc08553f
+  metadata.gz: d4d8ef476cd8a5f52d49b546eccc28e6e75277cd881d01667ea137c069c15b8a3a93a5029a855ae10ade990f8c8a5ecc61383e7b7f1c5922f0cf71babdf203df
+  data.tar.gz: 8b1dfa0578b38e11a317bb47ff3f2985e27236f5199a248431a49acc2f76bd88ed8bac2c6980ab066d19fd3f931ca0f122f8b19501899f2e0e38182cace55f3c

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 
 # Changelog
 
+## 0.11.0
+
+- `framework_version:` now resolves against the release manifest published by the design system, not only the version list shipped inside the gem, so a framework version released after your trmnlp install can be pinned without upgrading. The manifest is read once per run with a 2 second timeout. If the request fails, or the response is not a version list, the copy bundled in the gem is used and rendering continues. That bundled copy is refreshed here too: `latest` moves from 3.1.1 to 3.2.0.
+- `rake framework:sync` reads the published manifest by default. Pass a local design-system checkout (`rake framework:sync[/path/to/repo]`) for the previous behaviour.
+
+## 0.10.0
+
+- Added support for the `description` plugin setting, an optional one-line summary of the plugin. `trmnlp init` scaffolds the key in `src/settings.yml`, `trmnlp lint` reports descriptions longer than 35 characters (the hosted service's limit), and `trmnlp list` shows a DESCRIPTION column when any plugin has one. Only the length is checked. Storing the value needs the matching hosted service release; until then `trmnlp push` drops it, because it rewrites the local `settings.yml` from the server's response.
+- `trmnlp push` now offers to delete the server-side transform script when the project has no local `transform.*` file. Previously, deleting the file locally was a silent no-op: the server kept executing its copy and every `trmnlp pull` re-created the file. Answering yes sends `serverless_language: none` in the pushed settings.yml, which the server consumes as an explicit removal request. `--force` pushes skip the question and behave exactly as before; a failed server check never blocks the push.
+
 ## 0.9.0
 
 - Added OAuth2 support for local plugin preview (beta). Configure a provider with the flat `oauth_*` keys in `src/settings.yml` (authorize and token URLs, scopes, optional PKCE), which round-trip through `trmnlp push` and `pull`. Set `TRMNL_OAUTH_CLIENT_ID` and `TRMNL_OAUTH_CLIENT_SECRET` in your environment (credentials stay local and are never synced), and register `http://localhost:4567/oauth/callback` as the redirect URI in your OAuth app. `trmnlp serve` shows a Connect banner that runs the authorization code flow in the browser, stores the tokens in the cache directory (never in the project), and refreshes them before they expire. The access token is exposed to polling templates as `{{ oauth_access_token }}`, matching the hosted service. This is a beta feature; please report incorrect behaviour at https://github.com/usetrmnl/trmnlp/issues.

data/README.md

@@ -427,7 +427,9 @@ A complete worked example lives at [`examples/hn-stories/`](examples/hn-stories/
 
 The `settings.yml` file is part of the plugin definition, and is uploaded and downloaded by `trmnlp push` / `pull`.
 
-`framework_version:` pins the [TRMNL Design System](https://trmnl.com/framework) version this plugin renders against — `latest` (the default) tracks the newest release, or set a specific version for reproducibility. It lives here rather than in `.trmnlp.yml` so the value round-trips with the hosted plugin service.
+`framework_version:` pins the [TRMNL Design System](https://trmnl.com/framework) version this plugin renders against — `latest` (the default) tracks the newest release, or set a specific version for reproducibility. It lives here rather than in `.trmnlp.yml` so the value round-trips with the hosted plugin service. The list of pinnable versions is read from the [design system's published manifest](https://github.com/usetrmnl/trmnl-framework) once per run, so a newly released version can be pinned without upgrading trmnlp. If that request fails, the copy bundled in the gem is used.
+
+`description:` is an optional one-line summary of the plugin, up to 35 characters. `trmnlp lint` reports anything longer, and `trmnlp list` shows it next to each plugin name.
 
 See [TRMNL documentation](https://help.trmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0) for details on this file's contents.
 

data/db/data/framework_versions.yml

@@ -1,6 +1,6 @@
 # Mirrored from the TRMNL design-system source.
 # Refresh with `rake framework:sync` — do not edit manually.
-latest: 3.1.1
+latest: 3.2.0
 versions:
 - number: 0.0.1
   released_at: '2024-06-22'
@@ -70,3 +70,19 @@ versions:
   released_at: '2026-04-29'
 - number: 3.1.1
   released_at: '2026-05-01'
+- number: 3.1.2
+  released_at: '2026-07-09'
+- number: 3.1.3
+  released_at: '2026-07-14'
+- number: 3.1.4
+  released_at: '2026-07-15'
+- number: 3.1.5
+  released_at: '2026-07-16'
+- number: 3.1.6
+  released_at: '2026-07-17'
+- number: 3.1.7
+  released_at: '2026-07-18'
+- number: 3.1.8
+  released_at: '2026-07-23'
+- number: 3.2.0
+  released_at: '2026-08-03'

data/lib/trmnlp/commands/list.rb

@@ -9,6 +9,8 @@ module TRMNLP
       Options = Data.define(:dir, :quiet)
 
       PRIVATE_PLUGIN_ID = 37
+      ID_WIDTH = 8
+      RULE_WIDTH = 50
 
       def call
         authenticate!
@@ -25,15 +27,55 @@ module TRMNLP
         end
 
         reporter.info "Your plugins:\n\n"
-        reporter.info '  ID        NAME'
-        reporter.info "  #{'-' * 50}"
+        report_table(plugins)
+
+        reporter.info "\nTo clone a plugin:"
+        reporter.info '    trmnlp clone [folder_name] [id]'
+      end
+
+      private
+
+      def report_table(plugins)
+        return report_names(plugins) if plugins.none? { |plugin| description(plugin) }
+
+        report_names_and_descriptions(plugins)
+      end
+
+      def report_names(plugins)
+        ids = id_width(plugins)
+        report_header format("%-#{ids}s  %s", 'ID', 'NAME')
 
         plugins.each do |plugin|
-          reporter.info format('  %-8s  %s', plugin['id'], plugin['name'])
+          reporter.info format("  %-#{ids}s  %s", plugin['id'], plugin['name'])
         end
+      end
 
-        reporter.info "\nTo clone a plugin:"
-        reporter.info '    trmnlp clone [folder_name] [id]'
+      def report_names_and_descriptions(plugins)
+        ids = id_width(plugins)
+        names = column_width(plugins.map { |plugin| plugin['name'] }, 'NAME'.length)
+        report_header format("%-#{ids}s  %-#{names}s  %s", 'ID', 'NAME', 'DESCRIPTION')
+
+        plugins.each do |plugin|
+          row = format("  %-#{ids}s  %-#{names}s  %s", plugin['id'], plugin['name'], description(plugin))
+          reporter.info row.rstrip
+        end
+      end
+
+      # BYOS servers return a UUID for plugins created there and the original
+      # number for plugins imported from the hosted service, so one response
+      # can hold both widths.
+      def id_width(plugins) = column_width(plugins.map { |plugin| plugin['id'] }, ID_WIDTH)
+
+      def column_width(values, minimum) = [*values.map { |value| value.to_s.length }, minimum].max
+
+      def report_header(text)
+        reporter.info "  #{text}"
+        reporter.info "  #{'-' * [text.length, RULE_WIDTH].max}"
+      end
+
+      def description(plugin)
+        value = plugin['description'].to_s.strip
+        value unless value.empty?
       end
     end
   end

data/lib/trmnlp/commands/push.rb

@@ -38,11 +38,8 @@ module TRMNLP
           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
+        removal_requested = !is_new && confirm_server_transform_removal?(api, plugin_settings_id)
+        build_archive(removal_requested)
 
         response = api.post_plugin_setting_archive(plugin_settings_id, ZIP_PATH)
         paths.plugin_config.write(response.dig('data', 'settings_yaml'))
@@ -72,6 +69,51 @@ module TRMNLP
       ensure
         FileUtils.rm_f(ZIP_PATH)
       end
+
+      private
+
+      def build_archive(removal_requested)
+        Zip::File.open(ZIP_PATH, create: true) do |zip_file|
+          paths.src_files.each do |file|
+            next if removal_requested && file == paths.plugin_config
+
+            zip_file.add(File.basename(file), file)
+          end
+          if removal_requested
+            zip_file.get_output_stream('settings.yml') { |entry| entry.write(settings_yaml_with_removal_request) }
+          end
+        end
+      end
+
+      # Without this, deleting a local transform.* is a silent no-op: the server
+      # keeps executing its copy and every pull re-creates the file. The pushed
+      # settings.yml carries `serverless_language: none`, which the importer
+      # consumes as an explicit removal request.
+      def confirm_server_transform_removal?(api, plugin_settings_id)
+        return false if options.force
+        return false if paths.transform_file.first
+        return false unless server_transform?(api, plugin_settings_id)
+
+        question = 'The server has a transform script, but this project has no transform file. ' \
+                   'Delete it on the server too? (y/N) '
+        %w[y yes].include?(prompt(question).downcase)
+      end
+
+      def server_transform?(api, plugin_settings_id)
+        archive = api.get_plugin_setting_archive(plugin_settings_id)
+        begin
+          Zip::File.open(archive.path) { |zip_file| zip_file.any? { |entry| entry.name.start_with?('transform.') } }
+        ensure
+          archive.close
+        end
+      rescue Error
+        # Advisory check only — an unreadable archive must not block the push.
+        false
+      end
+
+      def settings_yaml_with_removal_request
+        config.plugin.settings.merge('serverless_language' => 'none').to_yaml
+      end
     end
   end
 end

data/lib/trmnlp/framework_version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'date'
+require 'faraday'
 require 'yaml'
 
 module TRMNLP
@@ -11,10 +13,31 @@ module TRMNLP
 
     DEFAULT_ASSET_HOST = 'https://trmnl.com'
     DATA_PATH = File.expand_path('../../db/data/framework_versions.yml', __dir__)
+    # DATA_PATH holds a copy of this file, refreshed by `rake framework:sync`.
+    MANIFEST_URL = 'https://raw.githubusercontent.com/usetrmnl/trmnl-framework/main/db/data/framework_versions.yml'
+    MANIFEST_TIMEOUT = 2
 
     attr_reader :number
 
-    def self.config = @config ||= YAML.load_file(DATA_PATH).freeze
+    def self.config = @config ||= (remote_config || YAML.load_file(DATA_PATH)).freeze
+
+    # Answers nil on any failure, so rendering never depends on the network.
+    # The shape check rejects error pages, which are also valid YAML.
+    def self.remote_config
+      response = Faraday.get(MANIFEST_URL) do |request|
+        request.options.open_timeout = MANIFEST_TIMEOUT
+        request.options.timeout = MANIFEST_TIMEOUT
+      end
+      return unless response.success?
+
+      # Release dates are quoted today, but the manifest is generated
+      # upstream and an unquoted date would otherwise be rejected here.
+      manifest = YAML.safe_load(response.body, permitted_classes: [Date])
+      manifest if manifest.is_a?(Hash) && manifest.key?('latest') && manifest.key?('versions')
+    rescue StandardError
+      nil
+    end
+    private_class_method :remote_config
 
     def self.version_numbers = config.fetch('versions').map { |v| v['number'] }.freeze
 

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Matches the hosted service's limit. There is no upstream file to sync
+      # from, so update this by hand when that limit changes, the same way
+      # db/data/form_fields.yml is kept current.
+      class DescriptionLength < Check
+        MAX_LENGTH = 35
+        MESSAGE = "Description should be <= #{MAX_LENGTH} characters long.".freeze
+
+        private
+
+        def pass? = source.plugin_description.length <= MAX_LENGTH
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/source.rb

@@ -16,6 +16,7 @@ module TRMNLP
       end
 
       def plugin_name = settings['name'].to_s
+      def plugin_description = settings['description'].to_s
       def settings = config.plugin.settings
       def custom_field_values = config.project.custom_fields
       def custom_field_definitions = config.plugin.custom_field_definitions

data/lib/trmnlp/lint.rb

@@ -4,6 +4,7 @@ require_relative 'lint/check'
 require_relative 'lint/source'
 require_relative 'lint/checks/title_casing'
 require_relative 'lint/checks/title_length'
+require_relative 'lint/checks/description_length'
 require_relative 'lint/checks/layouts_have_content'
 require_relative 'lint/checks/no_async_functions'
 require_relative 'lint/checks/waits_for_dom_load'
@@ -23,6 +24,7 @@ module TRMNLP
     CHECKS = [
       Checks::TitleCasing,
       Checks::TitleLength,
+      Checks::DescriptionLength,
       Checks::LayoutsHaveContent,
       Checks::NoAsyncFunctions,
       Checks::WaitsForDomLoad,

data/lib/trmnlp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TRMNLP
-  VERSION = '0.9.0'
+  VERSION = '0.11.0'
 end

data/templates/init/src/settings.yml

@@ -13,4 +13,5 @@ framework_version: latest
 polling_url: ''
 polling_headers: ''
 name: My Plugin
+description: ''
 refresh_interval: 1440

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -305,6 +305,7 @@ files:
 - lib/trmnlp/lint.rb
 - lib/trmnlp/lint/check.rb
 - lib/trmnlp/lint/checks/custom_fields_used.rb
+- lib/trmnlp/lint/checks/description_length.rb
 - lib/trmnlp/lint/checks/form_fields_valid.rb
 - lib/trmnlp/lint/checks/highcharts_animations_disabled.rb
 - lib/trmnlp/lint/checks/highcharts_elements_unique.rb