trmnl_preview 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d37a034edabdffdea4cfd43b0a768f43955d0d1d41d8b7d5d49a8c30de676525
-  data.tar.gz: cc6e4d027d53e52e4c05b1a1f35ddafbbf136fa3467c5b1015d5813397935b49
+  metadata.gz: bf11a528033d7882be345a627e2a480f1cdf95a5f9cef22d01f51f5b46012635
+  data.tar.gz: 973c3dc1b96f1d7a81ffa8e9fc82f403285d9449463d210684732a43028509d8
 SHA512:
-  metadata.gz: c55ca2009766d890fbfc851752281d587ee4f76d48df50eb144e4aff113f8ae7255c1003a9519f2182151b1dd8294edb566462306c5d7777661ef60ba0bd831e
-  data.tar.gz: 5060f91212a819e479a12ddf72d44e970d098781abdacedd994a1716bb2642201dc5c753b09ee1da3c69de2b3a6acf191cd847967c6ae412f53f08042eca1557
+  metadata.gz: 39963f376ff877a4170ce57564876e5cb4bd6eacc23de4b1792a6cba6cd01f4252579fe19c8d678f21144f37e9ba050ed03866b38a3f7aaa9a67521aa324fd04
+  data.tar.gz: 835b494bb56d29e9e4b607a482ae05466b08aa527ff38c00fae2a98e87524bbcbb6db78c9abd5dc8288c3b36692008107a1c9bbbdd298c36ddf1d435cd0d2e65

data/CHANGELOG.md

@@ -0,0 +1,192 @@
+
+# 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)
+
+## 0.6.1
+
+- Update trmnl-liquid to 0.4.0
+
+## 0.6.0
+
+- Drop trmnl-component in lieu of plain iframe
+- Add [trmnl-picker](https://github.com/usetrmnl/trmnl-picker) to support new TRMNL and BYOD screens
+- Fix mashup layout previews
+
+## 0.5.10
+
+- Fix interpolation of multi-line polling URLs with custom fields
+
+## 0.5.9
+
+- Add `pathname` dependency
+
+## 0.5.8
+
+- Improve Docker commands in `bin/trmnlp` (@jrand0m, @jbarreiros)
+
+## 0.5.7
+
+- Use the `trmnl-liquid` gem so tags and filters stay up-to-date with the hosted offering
+
+## 0.5.6
+
+- Fixed bug that left blank plugins on server after upload failed
+- Fixed bug creating upload.zip after previous upload had failed
+- Added support to read API key fromk `TRMNL_API_KEY` environment variable (@andi4000)
+- Fixed `init` command in Docker container (@jbarreiros)
+- Automatically remove ephemeral Docker container after exit (@andi4000)
+
+## 0.5.5
+
+- Added dark mode (@stephenyeargin)
+- Added override for `polling_url` in project config (@heroheman)
+- Reworked `bin/dev` into more generic `bin/trmnlp`
+- Fixed pull, push, and clone commands on Windows (@eugenio)
+
+## 0.5.4
+
+- Added `shared.liquid` file to template (@mariovisic)
+- Stringified custom field values to match production (@mariovisic)
+- Optimized image generation (@sd416)
+- Fixed preview from growing when JSON data becomes too wide (@stephenyeargin)
+
+## 0.5.3
+
+- Added support for [reusable markup](https://docs.trmnl.com/go/reusing-markup) in `shared.liquid`
+- Replaced custom case images with [\<trmnl-frame\> component](https://github.com/usetrmnl/trmnl-component)
+- Updated custom Liquid filters
+- Added API key validation during `trmnlp login`
+
+## 0.5.2
+
+- Added `time_zone` project config option, which is injected into `trmnl.user` variables
+- Fixed time zone to always be UTC, matching trmnl.com servers (#38)
+
+## 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.trmnl.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.trmnl.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
+- Add TRMNL's [custom plugin filters](https://help.trmnl.com/en/articles/10347358-custom-plugin-filters)
+- Add support for user-supplied custom filters
+
+## 0.3.1
+
+- Add live render
+
+## 0.3.0
+
+- Add poll button
+- Add case image overlays
+- Add `trmnlp build` command
+- Add support for `url` pointing to a local JSON data file
+
+## 0.2.0
+
+- Add "commands" concept to `trmnlp` executable
+- `trmnlp serve` improvements
+  - Add argument for plugin directory
+  - Add options `-b` and `-p` for host bind and port, respectively
+- Add Dockerfile
+
+## 0.1.2
+
+- Initial working release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Rockwell Schrock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,319 @@
+# 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).
+
+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:
+
+```
+.
+├── .trmnlp.yml
+├── bin
+│   └── trmnlp
+└── src
+    ├── full.liquid
+    ├── half_horizontal.liquid
+    ├── half_vertical.liquid
+    ├── quadrant.liquid
+    ├── shared.liquid
+    └── 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.
+
+```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
+trmnlp login                   # authenticate
+trmnlp clone [my_plugin] [id]  # first download
+cd [my_plugin]
+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`.
+
+If an environment variable is more convenient (for example in a CI/CD pipeline), you can set `$TRMNL_API_KEY` instead.
+
+## Running trmnlp
+
+The `bin/trmnlp` script is provided as a convenience. It will use the local Ruby gem if available, falling back to the `trmnl/trmnlp` Docker image.
+
+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.4
+- For PNG rendering (optional):
+  - Firefox
+  - ImageMagick
+
+```sh
+gem install trmnl_preview
+trmnlp serve
+```
+
+### Installing via Docker
+
+```sh
+docker run \
+    --publish 4567:4567 \
+    --volume "$(pwd):/plugin" \
+    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.
+
+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
+
+# 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:
+    user:
+      name: Peter Quill
+    plugin_settings:
+      instance_name: Kevin Bacon Facts
+
+```
+
+## 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, 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:
+
+```sh
+bin/rake
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/usetrmnl/trmnlp.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/rake

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __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')
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rake', 'rake')

data/bin/trmnlp

@@ -1,19 +1,18 @@
-#!/usr/bin/env ruby
+#! /usr/bin/env ruby
 # frozen_string_literal: true
 
-warn <<~MESSAGE
-  trmnlp requires Ruby 4.0 or newer.
+require 'thor'
 
-  You are running Ruby #{RUBY_VERSION}. RubyGems installed this notice
-  instead of trmnlp, because the current release cannot run on your Ruby.
+require_relative '../lib/trmnlp/cli'
 
-  To use trmnlp, either:
+# Force UTC to match trmnl.com server time zone
+ENV['TZ'] = 'UTC'
 
-    * Upgrade to Ruby 4.0 or newer, then run:
-        gem install trmnl_preview
-
-    * Or run it through Docker, no Ruby needed:
-        https://github.com/usetrmnl/trmnlp#installing-via-docker
-MESSAGE
-
-exit 1
+begin
+  TRMNLP::CLI.start
+rescue TRMNLP::Error => e
+  puts "Error: #{e.message}"
+  exit 1
+rescue Interrupt
+  exit 1
+end

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