trmnl_preview 0.7.2 → 0.8.0

data/lib/trmnlp/transform_backend/wrapper.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module TransformBackend
+    # Code wrappers shared by Subprocess and Http backends. Each method
+    # emits the canonical dispatch harness — read stdin → run user code
+    # → find run/transform/result/passthrough → serialize output — and
+    # delegates the final write to a language-appropriate `output_sink`
+    # snippet supplied by the caller. Subprocess writes to a tempfile
+    # path, Http writes to FD 3 for the production daemon to capture.
+    #
+    # Mirrors the hosted serverless runtime's code-wrapping behavior
+    # verbatim except for the configurable sink.
+    #
+    # NOTE: `output_sink` is spliced verbatim into the generated script as
+    # executable code. It MUST be trmnlp-generated (see Subprocess#sink_for
+    # and Http#sink_for) and never derived from user input or config — an
+    # attacker-influenced sink is arbitrary code execution in the transform
+    # process. Only `code` is untrusted; the sink is part of the harness.
+    module Wrapper
+      module_function
+
+      def python(code, output_sink)
+        <<~PYTHON
+          import sys, json, os
+          input = json.loads(sys.stdin.read())
+
+          #{code}
+
+          if callable(locals().get('run', None)):
+              output = run(input)
+          elif 'result' in dir():
+              output = result
+          else:
+              output = input
+          #{output_sink}
+        PYTHON
+      end
+
+      def ruby(code, output_sink)
+        <<~RUBY
+          require 'json'
+          input = JSON.parse($stdin.read)
+
+          #{code}
+
+          output = if defined?(run) == 'method'
+                     run(input)
+                   elsif defined?(result)
+                     result
+                   else
+                     input
+                   end
+          #{output_sink}
+        RUBY
+      end
+
+      # NOTE: node also accepts `function transform(input)` for
+      # production parity. Plugins authored against the hosted service
+      # using `transform` would otherwise silently pass input through.
+      def node(code, output_sink)
+        <<~JS
+          const input = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+
+          #{code}
+
+          let output;
+          if (typeof run === "function") {
+            output = run(input);
+          } else if (typeof transform === "function") {
+            output = transform(input);
+          } else if (typeof result !== "undefined") {
+            output = result;
+          } else {
+            output = input;
+          }
+          #{output_sink}
+        JS
+      end
+
+      # NOTE: strips a leading `<?php` tag from user code so plugin
+      # authors can write the file as a standalone .php script. The
+      # hosted service does the same.
+      def php(code, output_sink)
+        cleaned = code.sub(/\A\s*<\?php\s*/, '')
+        <<~PHP
+          <?php
+          $input = json_decode(file_get_contents('php://stdin'), true);
+
+          #{cleaned}
+
+          if (function_exists('run')) {
+              $output = run($input);
+          } elseif (isset($result)) {
+              $output = $result;
+          } else {
+              $output = $input;
+          }
+          #{output_sink}
+        PHP
+      end
+
+      def for(language, code, output_sink)
+        case language.to_s
+        when 'python' then python(code, output_sink)
+        when 'ruby'   then ruby(code, output_sink)
+        when 'node'   then node(code, output_sink)
+        when 'php'    then php(code, output_sink)
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/transform_client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  # Strategy host for serverless transform execution. Local plugin
+  # development hits the Subprocess backend by default — transforms
+  # run in trmnlp's own image alongside Ruby, no daemon required.
+  # Setting `serverless_daemon_url` in .trmnlp.yml swaps in the Http
+  # backend so plugin authors can target a real remote transform
+  # daemon (production parity testing, shared team daemons, etc.).
+  class TransformClient
+    # Mirrors the remote daemon's ExecResponse. `output` is the canonical
+    # JSON result; `stdout` carries user prints.
+    Result = Data.define(:stdout, :stderr, :output, :exit_code, :duration_ms, :error) do
+      def success? = error.nil? && exit_code.zero?
+    end
+
+    attr_reader :backend
+
+    # Returns nil when serverless is disabled in .trmnlp.yml so the
+    # pipeline can short-circuit without a per-request check.
+    def self.from_config(project_config)
+      runtime = project_config.transform_runtime
+      return nil if runtime.nil? || runtime.to_s == 'disabled'
+
+      new(backend: backend_for(project_config))
+    end
+
+    def self.backend_for(project_config)
+      if (url = project_config.serverless_daemon_url)
+        TransformBackend::Http.new(url: url, api_key: project_config.serverless_daemon_api_key)
+      else
+        TransformBackend::Subprocess.new
+      end
+    end
+
+    def initialize(backend:)
+      @backend = backend
+    end
+
+    def execute(code:, language:, stdin: '', timeout_seconds: 30)
+      backend.execute(code:, language:, stdin:, timeout_seconds:)
+    end
+  end
+end
+
+require_relative 'transform_backend/subprocess'
+require_relative 'transform_backend/http'

data/lib/trmnlp/transform_pipeline.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'reporter'
+require_relative 'transform_client'
+
+module TRMNLP
+  # Pipes assembled merge_variables through src/transform.{py,rb,php,js}
+  # when a serverless runtime is configured. Mirrors the hosted
+  # transform behavior: the transform receives the data (including the
+  # trmnl namespace) on stdin and its stdout JSON replaces the data.
+  # Failure modes surface via #error (rendered in the preview UI), not
+  # raised.
+  class TransformPipeline
+    attr_reader :error
+
+    def initialize(config:, paths:, reporter: Reporter.new)
+      @config = config
+      @paths = paths
+      @reporter = reporter
+    end
+
+    def call(data)
+      @error = nil
+      transform_path, inferred_language = paths.transform_file
+      return data unless transform_path && client
+
+      run(transform_path, inferred_language, data)
+    end
+
+    def reset! = @client = nil
+
+    private
+
+    attr_reader :config, :paths, :reporter
+
+    def client = @client ||= TransformClient.from_config(config.project)
+
+    def run(path, inferred_language, data)
+      language = config.plugin.serverless_language || inferred_language
+      result = client.execute(code: path.read, stdin: JSON.generate(data), language:)
+      return record_failure(result, data) unless result.success?
+
+      parse_output(result.output, data)
+    end
+
+    def record_failure(result, fallback)
+      @error = result.error || "transform exited #{result.exit_code}: #{result.stderr.strip}"
+      reporter.info("transform failed: #{@error}")
+      fallback
+    end
+
+    def parse_output(output, fallback)
+      transformed = JSON.parse(output)
+      transformed.is_a?(Hash) ? transformed : wrap_array(transformed)
+    rescue JSON::ParserError => e
+      @error = "transform produced non-JSON output: #{e.message}"
+      reporter.info(@error)
+      fallback
+    end
+
+    def wrap_array(json) = json.is_a?(Array) ? { data: json } : json
+  end
+end

data/lib/trmnlp/user_data_assembler.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/time'
+require 'json'
+
+module TRMNLP
+  class UserDataAssembler
+    DEFAULT_DEVICE_WIDTH = 800
+    DEFAULT_DEVICE_HEIGHT = 480
+
+    def initialize(config:, paths:, transform_pipeline:)
+      @config = config
+      @paths = paths
+      @transform_pipeline = transform_pipeline
+    end
+
+    # Assembles the merged data hash. The trmnl namespace is built first,
+    # layered with static_data / cached polled data / user_data_overrides,
+    # then piped through the transform. The trmnl namespace is re-applied
+    # after the transform so device, user, and plugin_settings survive
+    # even when the transform doesn't pass them through.
+    def call(device: {})
+      namespace = base_trmnl_data(device:)
+      merged = assemble(namespace)
+      result = transform_pipeline.call(merged)
+      result['trmnl'] = namespace['trmnl']
+      result
+    end
+
+    def device_from_params(params)
+      { 'width' => params[:width]&.to_i, 'height' => params[:height]&.to_i }.compact
+    end
+
+    private
+
+    attr_reader :config, :paths, :transform_pipeline
+
+    def assemble(namespace)
+      data = namespace.dup
+      merge_source_data!(data)
+      data.deep_merge!(config.project.user_data_overrides)
+      data
+    end
+
+    def merge_source_data!(data)
+      if config.plugin.static?
+        data.merge!(config.plugin.static_data)
+      elsif paths.user_data.exist?
+        data.merge!(JSON.parse(paths.user_data.read))
+      end
+    end
+
+    def base_trmnl_data(device:)
+      { 'trmnl' => trmnl_namespace(device:) }
+    end
+
+    def trmnl_namespace(device:)
+      {
+        'user' => user_namespace,
+        'device' => device_namespace(device),
+        'system' => { 'timestamp_utc' => Time.now.utc.to_i },
+        'plugin_settings' => plugin_settings_namespace
+      }
+    end
+
+    def user_namespace
+      tz = ActiveSupport::TimeZone.find_tzinfo(config.project.time_zone)
+      iana = tz.name
+      {
+        'name' => 'name', 'first_name' => 'first_name', 'last_name' => 'last_name',
+        'locale' => 'en', 'time_zone' => ActiveSupport::TimeZone::MAPPING.invert[iana] || iana,
+        'time_zone_iana' => iana, 'utc_offset' => tz.utc_offset
+      }
+    end
+
+    def device_namespace(device)
+      {
+        'friendly_id' => 'ABC123', 'percent_charged' => 85.0, 'wifi_strength' => 90,
+        'height' => device['height'] || DEFAULT_DEVICE_HEIGHT,
+        'width' => device['width'] || DEFAULT_DEVICE_WIDTH
+      }
+    end
+
+    def plugin_settings_namespace
+      {
+        'instance_name' => 'instance_name',
+        'strategy' => config.plugin.strategy,
+        'dark_mode' => config.plugin.dark_mode,
+        'polling_headers' => config.plugin.polling_headers_encoded,
+        'polling_url' => config.plugin.polling_url_text,
+        'custom_fields_values' => config.project.custom_fields
+      }
+    end
+  end
+end

data/lib/trmnlp/version.rb

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

data/lib/trmnlp/watcher.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'filewatcher'
+
+require_relative 'reporter'
+
+module TRMNLP
+  class Watcher
+    def initialize(config:, user_data_assembler:, transform_pipeline:, reporter: Reporter.new)
+      @config = config
+      @user_data_assembler = user_data_assembler
+      @transform_pipeline = transform_pipeline
+      @reporter = reporter
+    end
+
+    def start
+      @start ||= Thread.new { run }
+    end
+
+    def on_change(&block)
+      @view_change_callback = block
+    end
+
+    private
+
+    attr_reader :config, :user_data_assembler, :transform_pipeline, :reporter
+
+    def run
+      loop do
+        watch_cycle
+      rescue StandardError => e
+        reporter.info("error during live render: #{e}")
+      end
+    end
+
+    def watch_cycle
+      Filewatcher.new(config.project.watch_paths).watch do |changes|
+        reload_config!
+        notify(changes)
+      end
+    end
+
+    def reload_config!
+      config.project.reload!
+      config.plugin.reload!
+      transform_pipeline.reset! # config may have changed runtime config
+    end
+
+    # NOTE: transform.* changes don't trigger a re-poll — the transform
+    # runs inside user_data on every render against the cached polled
+    # response (or static_data), so editing the transform updates the
+    # preview without re-fetching the API.
+    def notify(changes)
+      data = user_data_assembler.call
+      return unless @view_change_callback
+
+      changes.each_key { |path| @view_change_callback.call(File.basename(path, '.liquid'), data) }
+    end
+  end
+end

data/lib/trmnlp.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module TRMNLP; end
+require 'oj'
+Oj.mimic_JSON
+require_relative 'trmnlp/errors'
+require_relative 'trmnlp/config'
+require_relative 'trmnlp/context'
+require_relative 'trmnlp/screen'
+require_relative 'trmnlp/version'

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/trmnlp

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# This script was automatically generated by `trmnlp init` but it's yours to modify!
+# Use this opportunity to set up environment variables, install dependencies, etc.
+#
+
+if command -v trmnlp &> /dev/null
+then
+    trmnlp "$@"
+    exit
+fi
+
+# Determine XDG config directory on host OS
+if [ -n "$XDG_CONFIG_HOME" ]; then
+    CONFIG_DIR="$XDG_CONFIG_HOME/trmnlp"
+else
+    CONFIG_DIR="$HOME/.config/trmnlp"
+fi
+
+if [ ! -d "$CONFIG_DIR" ]; then
+    mkdir -p "$CONFIG_DIR"
+fi
+
+if command -v docker &> /dev/null
+then
+    docker run \
+        -it \
+        --rm \
+        --publish 4567:4567 \
+        --volume "$(pwd):/plugin" \
+        --volume "$CONFIG_DIR:/root/.config/trmnlp" \
+        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,16 @@
+#
+# Changes to this file will be overwritten by `trmnlp pull`.
+#
+# Docs: https://help.trmnl.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
+framework_version: latest
+polling_url: ''
+polling_headers: ''
+name: My Plugin
+refresh_interval: 1440

data/templates/init/src/shared.liquid

@@ -0,0 +1 @@
+

data/templates/init/src/transform.py.example

@@ -0,0 +1,14 @@
+# Optional serverless transform.
+# Rename this file to `transform.py` (or transform.rb / transform.php / transform.js)
+# and it runs automatically — serverless transforms are enabled by default.
+# (Set `transform_runtime: disabled` in .trmnlp.yml to turn them off.)
+#
+# Define a `run(input)` function that takes the polled response (parsed
+# JSON, including the trmnl namespace) and returns any JSON-serialisable
+# value. The bundled transform-runtime wraps this and handles stdin/stdout.
+# This matches the hosted serverless contract — the same code runs in production.
+
+
+def run(input):
+    # Reshape `input` however you like, then return.
+    return input

data/trmnl_preview.gemspec

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'lib/trmnlp/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'trmnl_preview'
+  spec.version = TRMNLP::VERSION
+  spec.authors = ['Rockwell Schrock']
+  spec.email = ['rockwell@schrock.me']
+
+  spec.summary = 'Local web server to preview TRMNL plugins'
+  spec.description = 'Automatically rebuild and preview TRNML plugins in multiple views'
+  spec.homepage = 'https://github.com/usetrmnl/trmnlp'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/usetrmnl/trmnlp'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    [
+      'bin/**/*',
+      'db/**/*',
+      'lib/**/*',
+      'templates/**/{*,.*}',
+      'web/**/*',
+      'CHANGELOG.md',
+      'LICENSE.txt',
+      'README.md',
+      'trmnl_preview.gemspec'
+    ].flat_map { |glob| Dir[glob] }
+  end
+  spec.bindir = 'bin'
+  spec.executables = ['trmnlp']
+  spec.require_paths = ['lib']
+
+  # Web server
+  spec.add_dependency 'puma', '~> 8.0'
+  spec.add_dependency 'rackup', '~> 2.2'
+  spec.add_dependency 'sinatra', '~> 4.1'
+
+  # HTML rendering
+  spec.add_dependency 'activesupport', '~> 8.0'
+  spec.add_dependency 'trmnl-liquid', '~> 0.7.0'
+
+  # PNG rendering
+  # spec.add_dependency 'puppeteer-ruby', '~> 0.45.6'
+  spec.add_dependency 'mini_magick', '~> 5.3'
+  spec.add_dependency 'selenium-webdriver', '~> 4.44'
+
+  # Utilities
+  spec.add_dependency 'cgi', '~> 0.5'
+  spec.add_dependency 'faraday', '~> 2.1'
+  spec.add_dependency 'faraday-multipart', '~> 1.1'
+  spec.add_dependency 'filewatcher', '~> 3.0'
+  spec.add_dependency 'oj', '~> 3.17'
+  spec.add_dependency 'rexml', '~> 3.4'
+  spec.add_dependency 'rubyzip', '~> 3.3'
+  spec.add_dependency 'thor', '~> 1.3'
+  spec.add_dependency 'tzinfo-data', '~> 1.2025'
+  spec.add_dependency 'xdg', '~> 10.2'
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end