trmnl_preview 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f442804907f15903eb4e5f543ad94eb18fdef92f82d191e67c4554621ca3c74
-  data.tar.gz: 0e8df9b455430254cc007c28e9799155b6e75cccc675fd9790e9a260e998c84a
+  metadata.gz: bf11a528033d7882be345a627e2a480f1cdf95a5f9cef22d01f51f5b46012635
+  data.tar.gz: 973c3dc1b96f1d7a81ffa8e9fc82f403285d9449463d210684732a43028509d8
 SHA512:
-  metadata.gz: ae89a85a00a4b5719128dc4e198cda157085c905b914a3f30ebf14b17f7c2ff3d3c4f87552e0c455d0691671998c003b019cf34dd5f948859f64749f05b615c0
-  data.tar.gz: 59642ee5f4741bf88fbcedcdcc8af927ed80127b044afdc464144e660a283c055dd395d8e579d97b58b001e7f441ecafe63a838bb90f9ea6cc2ed4ea3f8aff69
+  metadata.gz: 39963f376ff877a4170ce57564876e5cb4bd6eacc23de4b1792a6cba6cd01f4252579fe19c8d678f21144f37e9ba050ed03866b38a3f7aaa9a67521aa324fd04
+  data.tar.gz: 835b494bb56d29e9e4b607a482ae05466b08aa527ff38c00fae2a98e87524bbcbb6db78c9abd5dc8288c3b36692008107a1c9bbbdd298c36ddf1d435cd0d2e65

data/CHANGELOG.md

@@ -1,6 +1,59 @@
 
 # Changelog
 
+## 0.8.0
+
+### Housekeeping
+
+- Upgraded the development, CI, and Docker baseline to Ruby 4.0.4
+- Replaced the faye-websocket live reload with server-sent events, removing the eventmachine dependency
+- Upgraded `filewatcher` to 3.x for Ruby 4.0 support
+- Upgraded `mini_magick` to 5.x (ImageMagick 7 only)
+- Upgraded `rubyzip` to 3.x
+- Upgraded `puma` to 8.x
+- Upgraded `oj` and `selenium-webdriver` to their latest releases
+- Upgraded `trmnl-liquid` to 0.7 and `xdg` to 10
+- Added the `cgi` gem, removed from Ruby's standard library in 4.0
+- Dropped the redundant `pathname` gem dependency; Ruby provides `Pathname` built in
+- Added `.rspec` configuration and a `Rakefile`
+
+### Refactor
+
+- Refactored screen generation into focused objects: `Screen`, `Screenshot`, `Renderer`, `ImageQuantizer`, `BrowserPool`, `Reporter`, `Watcher`, `Poller`, `UserDataAssembler`
+- Added support for `text/html` and `text/plain` polling responses with JSON body sniffing (#81)
+- Fixed Liquid conditionals (`{% if %}...{% endif %}`) spanning `polling_headers` values (#79)
+- Fixed multi-select custom_fields being coerced into JSON strings — arrays now preserved (#80)
+- Fixed `trmnl.device.{width,height}` in user-data so they reflect the picker's selected model (#94)
+- Fixed `Permission denied` from `trmnlp clone` on Linux when overwriting template files (#83)
+- Fixed deprecated `convert` warning by switching to mini_magick's `Magick` tool (#89)
+
+### Serverless Transforms
+
+- Added `transform_runtime:` config in `.trmnlp.yml` — serverless transforms are enabled by default and run whenever a `src/transform.*` file is present; set to `disabled` to turn them off
+- Added `serverless_daemon_url:` override for pointing at a remote transform daemon (production-fidelity testing, shared team daemons)
+- Added `serverless_language:` override (`python`, `ruby`, `php`, `node`)
+- Added detection of `src/transform.{py,rb,php,js}` with language inferred from extension
+- Added `TRMNLP::TransformClient` strategy host that selects `TransformBackend::Subprocess` (default) or `TransformBackend::Http` (when `serverless_daemon_url` is set) via `.from_config`
+- Added `TRMNLP::TransformBackend::Subprocess` — local subprocess execution mirroring the hosted serverless wrapper contract verbatim, output flows back via a per-execution tempfile
+- Added `python3`, `nodejs`, and `php-cli` to the main `Dockerfile`'s runtime stage alongside the existing `ruby` so all four supported transform languages work out of the box — no sidecar required
+- Added transform-error surfacing in the preview UI when execution fails
+- Added filewatcher re-poll when transform source changes (hot reload)
+- Added `examples/hn-stories/` — a complete worked example fetching Hacker News top stories and rendering across all four sizes
+
+### Framework Picker
+
+- Added `framework_version:` plugin setting in `src/settings.yml` (defaults to `latest`, supports pinning to any released version) — round-trips through `trmnlp push`/`pull` alongside the hosted plugin archive format
+- Added `framework_asset_host:` override in `.trmnlp.yml` for offline / mirrored development
+- Added `TRMNLP::FrameworkVersion` mirroring the hosted framework versioning
+- Added `rake framework:sync` to refresh `db/data/framework_versions.yml` from a local design-system checkout
+- Updated `render_html.erb` to derive CSS/JS URLs from the resolved framework version
+
+### FormField & Init Template
+
+- Added FormField schema vendored from the hosted service (`db/data/form_fields.yml`) covering the full field-type allowlist
+- Refreshed the `trmnlp init` template to scaffold `framework_version` and transform configuration, including a `transform.py.example`
+- Fixed non-portable `/bin/bash` shebang in the generated `bin/trmnlp` (#78)
+
 ## 0.7.0
 
 - Switch from Puppeteer + CDP to Selenium + WebDriver BiDi (@SorceressLyra)
@@ -29,7 +82,7 @@
 
 ## 0.5.7
 
-- Use the `trmnl-liquid` gem so tags and filters stay up-to-date with the core offering
+- Use the `trmnl-liquid` gem so tags and filters stay up-to-date with the hosted offering
 
 ## 0.5.6
 

data/README.md

@@ -1,15 +1,27 @@
 # trmnlp
 
+[![CI](https://github.com/usetrmnl/trmnlp/actions/workflows/ci.yaml/badge.svg)](https://github.com/usetrmnl/trmnlp/actions/workflows/ci.yaml)
+[![Gem Version](https://img.shields.io/gem/v/trmnl_preview)](https://rubygems.org/gems/trmnl_preview)
+
 A basic self-hosted web server to ease the development and sharing of [TRMNL](https://trmnl.com/) plugins.
 
 [Liquid](https://shopify.github.io/liquid/) templates are rendered leveraging the [TRMNL Design System](https://trmnl.com/framework). They may be generated as HTML (faster, and a good approximation of the final result) or as PNG images (slower, but more accurate).
 
-Custom Liquid filters and tags are provided by the [trmnl-liquid](https://github.com/usetrmnl/trmnl-liquid) gem.
-
 The server watches the filesystem for changes to the Liquid templates, seamlessly updating the preview without the need to refresh.
 
 ![Screenshot](docs/preview.png)
 
+## Quick Start
+
+```sh
+gem install trmnl_preview     # install
+trmnlp init my_plugin         # scaffold a project
+cd my_plugin
+trmnlp serve                  # preview at http://localhost:4567
+```
+
+No Ruby on hand? Run it through Docker instead — see [Installing via Docker](#installing-via-docker).
+
 ## Project Structure
 
 This is the structure of a plugin project:
@@ -18,7 +30,7 @@ This is the structure of a plugin project:
 .
 ├── .trmnlp.yml
 ├── bin
-│   └── dev
+│   └── trmnlp
 └── src
     ├── full.liquid
     ├── half_horizontal.liquid
@@ -28,6 +40,16 @@ This is the structure of a plugin project:
     └── settings.yml
 ```
 
+| File | Purpose |
+|---|---|
+| `.trmnlp.yml` | Local dev-server config — not uploaded to TRMNL |
+| `src/full.liquid` | Markup for the full screen |
+| `src/half_horizontal.liquid` | Top or bottom half of a stacked mashup |
+| `src/half_vertical.liquid` | Left or right half of a side-by-side mashup |
+| `src/quadrant.liquid` | One quarter of a 2x2 mashup |
+| `src/shared.liquid` | Reusable markup included by the other templates |
+| `src/settings.yml` | Plugin configuration — uploaded to TRMNL |
+
 ## Creating a New Plugin
 
 You can start building a plugin locally, then `push` it to the TRMNL server for display on your device.
@@ -52,6 +74,23 @@ trmnlp serve                   # develop locally
 trmnlp push                    # upload
 ```
 
+## Commands
+
+| Command | Description |
+|---|---|
+| `trmnlp init NAME` | Start a new plugin project |
+| `trmnlp serve` | Start a local dev server |
+| `trmnlp build` | Generate static HTML files |
+| `trmnlp lint` | Check plugin code against TRMNL best practices |
+| `trmnlp login` | Authenticate with TRMNL server |
+| `trmnlp list` | List private plugins from TRMNL server |
+| `trmnlp clone NAME ID` | Copy a plugin project from TRMNL server |
+| `trmnlp pull` | Download latest plugin settings from TRMNL server |
+| `trmnlp push` | Upload latest plugin settings to TRMNL server |
+| `trmnlp version` | Show version |
+
+`trmnlp lint` exits non-zero when it finds issues, so you can gate CI on it. Run `trmnlp help` for all flags.
+
 ## Authentication
 
 The `trmnlp login` command saves your API key to `~/.config/trmnlp/config.yml`.
@@ -64,11 +103,13 @@ The `bin/trmnlp` script is provided as a convenience. It will use the local Ruby
 
 You can modify the `bin/trmnlp` script to set up environment variables (plugin secrets, etc.) before running the server.
 
+**Gem or Docker?** Install the gem if you already have Ruby >= 3.4 — it has the fastest startup. Use Docker for zero local setup.
+
 ### Installing via RubyGems
 
 Prerequisites:
 
-- Ruby 3.x
+- Ruby >= 3.4
 - For PNG rendering (optional):
   - Firefox
   - ImageMagick
@@ -87,6 +128,61 @@ docker run \
     trmnl/trmnlp serve
 ```
 
+Inside a container, `serve` binds to `0.0.0.0` automatically (it detects `/.dockerenv`) so the preview is reachable from your host browser. Outside Docker it binds to `127.0.0.1`.
+
+Swap `serve` for any other command (`lint`, `login`, `clone`, etc.) to run it in a one-off container.
+
+#### Interactive Mode
+
+For running multiple commands (login, clone, serve), you can start an interactive shell:
+
+```sh
+docker run -it \
+    --publish 4567:4567 \
+    --volume "$HOME/.config/trmnlp:/root/.config/trmnlp" \
+    --volume "$(pwd):/plugin" \
+    --entrypoint /bin/bash \
+    trmnl/trmnlp
+```
+
+Then run commands inside the container:
+
+```sh
+trmnlp login
+trmnlp clone my_plugin 12345
+cd my_plugin
+trmnlp serve
+```
+
+The config volume (`$HOME/.config/trmnlp`) persists your API key between sessions.
+
+#### Docker Compose
+
+For a checked-in config — like [`examples/hn-stories/`](examples/hn-stories/) uses — a minimal `docker-compose.yml`:
+
+```yaml
+services:
+  trmnlp:
+    image: trmnl/trmnlp
+    command: ["serve"]
+    ports:
+      - "4567:4567"
+    volumes:
+      - .:/plugin
+```
+
+Then `docker compose up`.
+
+#### Building Locally
+
+To build the Docker image from source:
+
+```sh
+git clone https://github.com/usetrmnl/trmnlp.git
+cd trmnlp
+docker build -t 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.
@@ -110,6 +206,18 @@ custom_fields:
 # Time zone IANA identifier to inject into trmnl.user; see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 time_zone: America/New_York
 
+# Serverless transforms run automatically when a src/transform.*
+# file is present. Set to 'disabled' to turn off.
+transform_runtime: enabled
+
+# Optional remote transform daemon URL — when set, transforms POST
+# here instead of running locally. Useful for production-fidelity
+# testing against a real microVM daemon.
+# serverless_daemon_url: https://transforms.your-team.example
+
+# Optional explicit language for src/transform.* (otherwise inferred from extension)
+# serverless_language: python
+
 # override variables
 variables:
   trmnl:
@@ -120,13 +228,80 @@ variables:
 
 ```
 
+## Serverless Transforms
+
+`trmnlp` can run a transform script (`python`, `ruby`, `php`, or `node`) against the polled API response before handing data to your Liquid templates — matching the hosted plugin service's behavior.
+
+Drop a file at `src/transform.{py,rb,php,js}` and define a `run(input)` function — transforms are enabled by default, so it runs automatically. To turn them off, set `transform_runtime: disabled` in `.trmnlp.yml`.
+
+> **Heads up:** because transforms run by default, a plugin you `clone` or `pull` from somewhere else will execute its `src/transform.*` code on your machine the first time you preview it — there is no opt-in prompt. Review a third-party plugin's transform script before serving it, or set `transform_runtime: disabled`.
+
+The transform receives the polled response on stdin as JSON; whatever `run(input)` returns becomes the new merge data.
+
+Example `src/transform.py`:
+
+```python
+def run(input):
+    return {"items": [x["title"] for x in input["data"]]}
+```
+
+The trmnlp image bundles `python3`, `node`, `php`, and `ruby` — no sidecar daemon required.
+
+### Language detection
+
+The transform language comes from the **file extension**:
+
+| File              | Language |
+|-------------------|----------|
+| `src/transform.py`  | `python` |
+| `src/transform.rb`  | `ruby`   |
+| `src/transform.js`  | `node`   |
+| `src/transform.php` | `php`    |
+
+`trmnlp push` uploads the file under its own name, and the hosted service records `serverless_language` from the extension automatically — you don't need to set it by hand. `trmnlp pull` / `trmnlp clone` bring the transform file back under the same name.
+
+### Pointing at a remote daemon
+
+For production-fidelity testing against a real microVM daemon, set `serverless_daemon_url:` in `.trmnlp.yml`:
+
+```yaml
+transform_runtime: enabled
+serverless_daemon_url: https://transforms.your-team.example
+```
+
+Provide the daemon's bearer token via `$TRMNL_SERVERLESS_DAEMON_API_KEY` (env-first, mirroring how `$TRMNL_API_KEY` works for trmnl.com auth):
+
+```sh
+export TRMNL_SERVERLESS_DAEMON_API_KEY=...
+trmnlp serve
+```
+
+Or commit a per-project value to `.trmnlp.yml` as `serverless_daemon_api_key:` — though the env var is preferred to keep the secret out of version control.
+
+A complete worked example lives at [`examples/hn-stories/`](examples/hn-stories/) — a polling plugin that fetches the Hacker News top-stories list, enriches each story via additional HTTPS calls from inside the transform, and renders the result with TRMNL design-system markup across all four sizes. `cd examples/hn-stories && docker compose up` and you're running it.
+
 ## `src/settings.yml` Reference (Plugin Config)
 
-The `settings.yml` file is part of the plugin definition. 
+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.
 
 See [TRMNL documentation](https://help.trmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0) for details on this file's contents.
 
 
+## Development
+
+To run trmnlp from a checkout of this repo — handy for trying unreleased changes or contributing:
+
+```sh
+git clone https://github.com/usetrmnl/trmnlp.git
+cd trmnlp
+bundle install
+bundle exec bin/trmnlp serve
+```
+
+The repo pins its Ruby version in `.ruby-version` — a version manager will pick it up when you `cd` in. This `bin/trmnlp` runs the CLI straight from `lib/`; it's a different script from the gem-or-Docker `bin/trmnlp` that `trmnlp init` scaffolds into a plugin project.
+
 ## Tests
 
 To test, run:

data/bin/rake

@@ -8,12 +8,12 @@
 # this file is here to facilitate running it.
 #
 
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
 
-bundle_binstub = File.expand_path("bundle", __dir__)
+bundle_binstub = File.expand_path('bundle', __dir__)
 
 if File.file?(bundle_binstub)
-  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
     load(bundle_binstub)
   else
     abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
@@ -21,7 +21,7 @@ Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this
   end
 end
 
-require "rubygems"
-require "bundler/setup"
+require 'rubygems'
+require 'bundler/setup'
 
-load Gem.bin_path("rake", "rake")
+load Gem.bin_path('rake', 'rake')

data/bin/trmnlp

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'thor'
 

data/db/data/form_fields.yml

@@ -0,0 +1,24 @@
+# Form-field schema vendored from the TRMNL hosted service.
+#
+# Unlike framework_versions.yml there is no upstream YAML to sync from —
+# the canonical schema lives in the hosted service's Ruby code. Refresh
+# this file by hand when that schema changes.
+#
+# author_bio is included although the hosted service validates it on a
+# separate branch (so it is absent from the hosted FIELDS allowlist) —
+# it is still a real field type a plugin may declare.
+required_keys:
+  - keyname
+  - field_type
+  - name
+field_types:
+  - text
+  - string
+  - number
+  - password
+  - boolean
+  - xhrString
+  - xhrSelect
+  - xhrFunction
+  - select
+  - author_bio

data/db/data/framework_versions.yml

@@ -0,0 +1,72 @@
+# Mirrored from the TRMNL design-system source.
+# Refresh with `rake framework:sync` — do not edit manually.
+latest: 3.1.1
+versions:
+- number: 0.0.1
+  released_at: '2024-06-22'
+- number: 0.0.2
+  released_at: '2024-06-23'
+- number: 0.0.3
+  released_at: '2024-07-09'
+- number: 0.0.4
+  released_at: '2024-07-11'
+- number: 0.0.5
+  released_at: '2024-07-14'
+- number: 0.0.6
+  released_at: '2024-08-18'
+- number: 0.0.7
+  released_at: '2024-09-19'
+- number: 1.0.0
+  released_at: '2024-11-03'
+- number: 1.0.1
+  released_at: '2025-01-21'
+- number: 1.0.2
+  released_at: '2025-02-04'
+- number: 1.0.3
+  released_at: '2025-02-06'
+- number: 1.0.4
+  released_at: '2025-02-24'
+- number: 1.0.5
+  released_at: '2025-04-23'
+- number: 1.1.0
+  released_at: '2025-05-19'
+- number: 1.1.1
+  released_at: '2025-05-20'
+- number: 1.2.0
+  released_at: '2025-07-28'
+- number: 2.0.0
+  released_at: '2025-09-14'
+- number: 2.0.1
+  released_at: '2025-11-10'
+- number: 2.1.0
+  released_at: '2025-12-30'
+- number: 2.2.0
+  released_at: '2026-01-13'
+- number: 2.2.1
+  released_at: '2026-01-16'
+- number: 2.3.0
+  released_at: '2026-02-07'
+- number: 2.3.1
+  released_at: '2026-02-09'
+- number: 2.3.2
+  released_at: '2026-02-26'
+- number: 2.3.3
+  released_at: '2026-03-02'
+- number: 2.3.7
+  released_at: '2026-03-20'
+- number: 3.0.0
+  released_at: '2026-04-01'
+- number: 3.0.1
+  released_at: '2026-04-03'
+- number: 3.0.2
+  released_at: '2026-04-03'
+- number: 3.0.3
+  released_at: '2026-04-07'
+- number: 3.0.4
+  released_at: '2026-04-29'
+- number: 3.0.5
+  released_at: '2026-05-01'
+- number: 3.1.0
+  released_at: '2026-04-29'
+- number: 3.1.1
+  released_at: '2026-05-01'

data/lib/trmnlp/api_client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'faraday'
 require 'faraday/multipart'
 
@@ -9,20 +11,36 @@ module TRMNLP
       @config = config
     end
 
+    def get_me
+      response = conn.get('me')
+
+      raise Error, "failed to fetch user info: #{response.status} #{response.body}" unless response.status == 200
+
+      JSON.parse(response.body)['data']
+    end
+
+    def get_plugin_settings
+      response = conn.get('plugin_settings')
+
+      raise Error, "failed to list plugin settings: #{response.status} #{response.body}" unless response.status == 200
+
+      JSON.parse(response.body)['data']
+    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 temp file IO
-        temp_file
-      else
+      unless response.status == 200
         raise Error, "failed to download plugin settings archive: #{response.status} #{response.body}"
       end
+
+      temp_file = Tempfile.new(["plugin_settings_#{id}", '.zip'])
+      temp_file.binmode
+      temp_file.write(response.body)
+      temp_file.rewind
+
+      # return the temp file IO
+      temp_file
     end
 
     def post_plugin_setting_archive(id, path)
@@ -36,37 +54,33 @@ module TRMNLP
 
       filepart.close
 
-      if response.status == 200
-        JSON.parse(response.body)
-      else
+      unless response.status == 200
         raise Error, "failed to upload plugin settings archive: #{response.status} #{response.body}"
       end
+
+      JSON.parse(response.body)
     end
 
     def post_plugin_setting(params)
-      response = conn.post("plugin_settings", params.to_json, content_type: 'application/json')
+      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
+      raise Error, "failed to create plugin setting: #{response.status} #{response.body}" unless response.status == 200
+
+      JSON.parse(response.body)
     end
 
     def delete_plugin_setting(id)
       response = conn.delete("plugin_settings/#{id}")
 
-      if response.status == 204
-        true
-      else
-        raise Error, "failed to delete plugin setting: #{response.status} #{response.body}"
-      end
+      raise Error, "failed to delete plugin setting: #{response.status} #{response.body}" unless response.status == 204
+
+      true
     end
 
     private
-  
+
     attr_reader :config
-  
+
     def api_uri = config.app.api_uri
 
     def conn
@@ -75,12 +89,11 @@ module TRMNLP
       end
     end
 
-
     def headers
       {
         'Authorization' => "Bearer #{config.app.api_key}",
-        'User-Agent' => "trmnlp/#{VERSION}",
+        'User-Agent' => "trmnlp/#{VERSION}"
       }
     end
   end
-end
+end