trmnl_preview 0.8.2 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 236a5502b02ab161fffc5330fc712c329810f877038c71baadc86b376e607157
-  data.tar.gz: 41400bbbe0b54639311ae928280277ee1717f58f1de74bd71ab92f213bbe92db
+  metadata.gz: 9fe003b113f4c1d832529b4d01cc931a8eb63259f385db8d6ff2dfca919a7cb9
+  data.tar.gz: 2254239e25186dab5f29bebf22ea8a87a180362521cf89a40900d86dda9bb9fc
 SHA512:
-  metadata.gz: 604a7f74231c2e738dbf61995469a64e488cc1d69fa9eb84076fb9badfb2d83fd8c490fa261154471852e7c7effb6071e458d40e748bc70de7ea27455d5a8485
-  data.tar.gz: c4396159f68882180618578725f2e386e703a9d992a195a5ce2de463d8dab407d9b0a30655495963e0b1af35ee2ab0813fae75ed77633d616312fa64246ef753
+  metadata.gz: d5e588f871e595f7c8dd637b6a2203cc1bde1696b91a5c397b1c176c4306f28e4f96ecc76a583f23da75ab3355a4288897b2ee823c7d8e1d658a2114c13d6f6d
+  data.tar.gz: 55efd439389300e0b18fe29025446632dd04412564a6ff36f8bea60d06f12e324bf18c97429b237d90df3eda94262a6009158cd82df8aab30b3b629dd6d1ff5e

data/CHANGELOG.md

@@ -1,6 +1,20 @@
 
 # Changelog
 
+## 0.8.4
+
+- Fixed `trmnlp serve` hanging after switching between browser tabs. Live reload now uses `rack.hijack` so SSE connections release their Puma worker thread immediately instead of holding it for the lifetime of the tab.
+- Fixed Ctrl-C requiring three presses to stop the dev server. filewatcher 3.0.1 was clobbering Puma's signal handlers with its own `trap('INT') { exit }`.
+- Fixed scaffolded plugins silently skipping their transform when `settings.yml` had `serverless_language: ''`. The empty string was treated as truthy in Ruby and short-circuited the file-extension fallback.
+- Docker examples in the README now use `--pull always` (and `pull_policy: always` for Compose) so a new release is picked up on the next `docker run` without a manual pull.
+
+## 0.8.3
+
+- `trmnlp init` and `trmnlp clone` now scaffold a `.github/workflows/trmnl.yml` CI workflow and a `.gitignore`, and run `git init -b main`, so a cloned plugin is ready to push to GitHub and deploy on every commit to `main`
+- Added `--skip-git` to `trmnlp init` and `trmnlp clone` for projects that manage Git themselves
+- The Docker image now ships `git` so the `docker run trmnl/trmnlp clone` flow leaves a ready-to-push project on the host
+- View templates now ship canonical `layout` + `title_bar` markup that passes `trmnlp lint`
+
 ## 0.8.2
 
 - Fixed `framework_version: latest` rendering against the auto-upgrading `/latest/` asset path instead of the current concrete release, matching the hosted service (#99)

data/README.md

@@ -28,6 +28,10 @@ This is the structure of a plugin project:
 
 ```
 .
+├── .github
+│   └── workflows
+│       └── trmnl.yml
+├── .gitignore
 ├── .trmnlp.yml
 ├── bin
 │   └── trmnlp
@@ -42,6 +46,8 @@ This is the structure of a plugin project:
 
 | File | Purpose |
 |---|---|
+| `.github/workflows/trmnl.yml` | GitHub Actions workflow — lints every PR, deploys to TRMNL on `main` |
+| `.gitignore` | Keeps `trmnlp build` output out of version control |
 | `.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 |
@@ -123,9 +129,12 @@ If an environment variable is more convenient (for example in a CI/CD pipeline),
 
 ## Continuous Integration
 
-`trmnlp` runs in GitHub Actions without `trmnlp login` — set the `TRMNL_API_KEY`
-environment variable and it's used in place of the saved config. Add it as a
-repository secret, then drop this into `.github/workflows/trmnl.yml`:
+`trmnlp init` and `trmnlp clone` scaffold a `.github/workflows/trmnl.yml`
+workflow and initialize a Git repository, so a fresh project is ready to push
+to GitHub. The workflow runs in GitHub Actions without `trmnlp login` — set the
+`TRMNL_API_KEY` environment variable and it's used in place of the saved
+config. Add it as a repository secret to activate the workflow; it looks like
+this:
 
 ```yaml
 name: TRMNL
@@ -194,11 +203,14 @@ trmnlp serve
 
 ```sh
 docker run \
+    --pull always \
     --publish 4567:4567 \
     --volume "$(pwd):/plugin" \
     trmnl/trmnlp serve
 ```
 
+`--pull always` checks the registry on every run and pulls a newer image if one exists, so you don't have to remember to `docker pull` after each release.
+
 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.
@@ -209,6 +221,7 @@ For running multiple commands (login, clone, serve), you can start an interactiv
 
 ```sh
 docker run -it \
+    --pull always \
     --publish 4567:4567 \
     --volume "$HOME/.config/trmnlp:/root/.config/trmnlp" \
     --volume "$(pwd):/plugin" \
@@ -235,6 +248,7 @@ For a checked-in config — like [`examples/hn-stories/`](examples/hn-stories/)
 services:
   trmnlp:
     image: trmnl/trmnlp
+    pull_policy: always
     command: ["serve"]
     ports:
       - "4567:4567"

data/lib/trmnlp/app.rb

@@ -77,17 +77,40 @@ module TRMNLP
       JSON.pretty_generate(@user_data_assembler.call(device:))
     end
 
-    # Live reload is a one-directional server->browser push, so it uses
-    # server-sent events rather than a websocket. Each client gets a blocking
-    # queue; the stream thread parks on queue.pop until the watcher broadcasts.
+    # Live reload uses rack.hijack so the Puma worker thread is released the
+    # instant we have the raw socket — broadcasting then runs on our own
+    # thread, never competing with HTTP request workers. Adapted from the
+    # Faye::EventSource pattern in faye-websocket (lib/faye/rack_stream.rb)
+    # but without the EventMachine dependency: where Faye uses EM.attach to
+    # get a reactor callback on socket close, we detect close synchronously
+    # via the IOError/EPIPE raised by the next heartbeat write.
+    HEARTBEAT_SECONDS = 5
+
     get '/live_reload' do
-      content_type 'text/event-stream'
+      hijack = env['rack.hijack']
+      halt 500, 'rack.hijack unavailable' unless hijack
+      hijack.call
+      io = env['rack.hijack_io']
+
       queue = Thread::Queue.new
       @live_reload_clients << queue
-      stream(:keep_open) do |out|
-        out.callback { @live_reload_clients.delete(queue) }
-        out << queue.pop until out.closed?
+
+      Thread.new do
+        io.write("HTTP/1.1 200 OK\r\n" \
+                 "Content-Type: text/event-stream\r\n" \
+                 "Cache-Control: no-cache\r\n" \
+                 "Connection: close\r\n\r\n")
+        run_live_reload_loop(io, queue)
+      rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+        # client disconnected mid-write — normal termination
+      ensure
+        @live_reload_clients.delete(queue)
+        io.close
       end
+
+      # -1 status tells the server we've hijacked the response. The body
+      # is never iterated; the thread above owns the socket from here.
+      [-1, {}, []]
     end
 
     get '/poll' do
@@ -128,6 +151,16 @@ module TRMNLP
 
     private
 
+    # On timeout (queue idle), a colon-prefixed SSE comment line both
+    # keeps proxies awake and surfaces a dead client via the next
+    # io.write — the route's outer rescue then cleans up.
+    def run_live_reload_loop(io, queue)
+      loop do
+        message = queue.pop(timeout: HEARTBEAT_SECONDS)
+        io.write(message || ": heartbeat\n\n")
+      end
+    end
+
     # ScreenGenerator is request-scoped — it carries the per-request width,
     # height, and color_depth — so it is built here rather than on the shared
     # Context graph. Screenshots are a serve-only concern and would not belong

data/lib/trmnlp/cli.rb

@@ -34,11 +34,13 @@ module TRMNLP
 
     desc 'init NAME', 'Start a new plugin project'
     method_option :skip_liquid, type: :boolean, default: false, desc: 'Skip generating liquid templates'
+    method_option :skip_git, type: :boolean, default: false, desc: 'Skip initializing a git repository'
     def init(name)
       Commands::Init.run(options, name)
     end
 
     desc 'clone NAME ID', 'Copy a plugin project from TRMNL server'
+    method_option :skip_git, type: :boolean, default: false, desc: 'Skip initializing a git repository'
     def clone(name, id)
       Commands::Clone.run(options, name, id)
     end

data/lib/trmnlp/commands/clone.rb

@@ -7,7 +7,7 @@ require_relative 'pull'
 module TRMNLP
   module Commands
     class Clone < Base
-      Options = Data.define(:dir, :quiet)
+      Options = Data.define(:dir, :quiet, :skip_git)
 
       def call(directory_name, id)
         authenticate!
@@ -15,7 +15,7 @@ module TRMNLP
         destination_path = Pathname.new(options.dir).join(directory_name)
         raise DirectoryExists, "directory #{destination_path} already exists, aborting" if destination_path.exist?
 
-        Init.run({ dir: options.dir, skip_liquid: true, quiet: true }, directory_name)
+        Init.run({ dir: options.dir, skip_liquid: true, quiet: true, skip_git: options.skip_git }, directory_name)
 
         Pull.run({ dir: destination_path.to_s, force: true, id: id })
 

data/lib/trmnlp/commands/init.rb

@@ -7,7 +7,7 @@ require_relative 'base'
 module TRMNLP
   module Commands
     class Init < Base
-      Options = Data.define(:dir, :quiet, :skip_liquid)
+      Options = Data.define(:dir, :quiet, :skip_liquid, :skip_git)
 
       def call(name)
         destination_dir = Pathname.new(options.dir).join(name)
@@ -17,7 +17,9 @@ module TRMNLP
           destination_dir.mkpath
         end
 
-        template_dir.glob('**/{*,.*}').each do |source_pathname|
+        # NOTE: FNM_DOTMATCH so the glob descends into hidden template
+        # directories (e.g. .github/); without it those files are skipped.
+        template_dir.glob('**/{*,.*}', File::FNM_DOTMATCH).each do |source_pathname|
           next if source_pathname.directory?
           next if options.skip_liquid && source_pathname.extname == '.liquid'
 
@@ -41,6 +43,8 @@ module TRMNLP
           destination_pathname.chmod(destination_pathname.stat.mode | 0o200)
         end
 
+        init_git_repo(destination_dir) unless options.skip_git
+
         reporter.info <<~HEREDOC
 
           To start the local server:
@@ -58,6 +62,13 @@ module TRMNLP
       private
 
       def template_dir = paths.templates_dir.join('init')
+
+      # Make the scaffold a Git repository on `main` so it's ready to push
+      # to GitHub (the workflow's `branches: [main]` trigger requires it,
+      # regardless of the host's init.defaultBranch).
+      # Does nothing when git is unavailable — `system` returns nil rather
+      # than raising, so the scaffold itself still succeeds.
+      def init_git_repo(dir) = system('git', 'init', '-q', '-b', 'main', dir.to_s)
     end
   end
 end

data/lib/trmnlp/commands/serve.rb

@@ -22,6 +22,9 @@ module TRMNLP
         App.set(:browser_pool, BrowserPool.new(driver_factory: FirefoxDriver.method(:build)))
         App.set(:bind, options.bind)
         App.set(:port, options.port)
+        # Each live-reload SSE connection holds a Puma thread for the tab's
+        # lifetime; the default 0:5 pool runs out fast with multiple tabs open.
+        App.set(:server_settings, Threads: '1:16')
         permit_all_hosts if codespaces?
 
         # Finally, start the app!

data/lib/trmnlp/config/plugin.rb

@@ -73,8 +73,13 @@ module TRMNLP
       # Explicit language for transform.* code. If absent, the language
       # is inferred from the file extension by Paths#transform_file.
       # This one lives on the plugin (settings.yml) because production
-      # stores it on the plugin_setting record.
-      def serverless_language = @config['serverless_language']
+      # stores it on the plugin_setting record. The scaffold emits
+      # `serverless_language: ''`, so empty strings collapse to nil here
+      # to let the `||` in the pipeline fall through to the inferred value.
+      def serverless_language
+        value = @config['serverless_language']
+        value unless value.to_s.empty?
+      end
 
       # The TRMNL design-system version this plugin renders against.
       # Lives on the plugin (settings.yml), like serverless_language,

data/lib/trmnlp/version.rb

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

data/lib/trmnlp/watcher.rb

@@ -4,6 +4,24 @@ require 'filewatcher'
 
 require_relative 'reporter'
 
+# filewatcher 3.0.1's #watch installs `trap('INT') { exit }` (and HUP/TERM)
+# unconditionally, clobbering Puma's clean-shutdown handler — Ctrl-C then
+# raises SystemExit instead of triggering Puma's graceful stop, which is
+# why the container needs three SIGINTs to die. The gem offers no opt-out;
+# its supported shutdown is Filewatcher#stop, which we're not using. We
+# replace the trap-installing #watch with the rest of its body so signals
+# fall through to whatever handler the host process installed (Puma).
+Filewatcher.prepend(Module.new do
+  def watch(&on_update)
+    @on_update = on_update
+    @keep_watching = true
+    yield({ '' => '' }) if @immediate
+    main_cycle
+    @end_snapshot = current_snapshot
+    finalize(&on_update)
+  end
+end)
+
 module TRMNLP
   class Watcher
     def initialize(config:, user_data_assembler:, transform_pipeline:, reporter: Reporter.new)

data/templates/init/.github/workflows/trmnl.yml

@@ -0,0 +1,30 @@
+name: TRMNL
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+      - run: gem install trmnl_preview
+      - run: trmnlp lint
+
+  push:
+    needs: lint
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+      - run: gem install trmnl_preview
+      - run: trmnlp push --force
+        env:
+          TRMNL_API_KEY: ${{ secrets.TRMNL_API_KEY }}

data/templates/init/.gitignore

@@ -0,0 +1,2 @@
+# trmnlp build output
+_build/

data/templates/init/src/full.liquid

@@ -1 +1,7 @@
-full!
+<div class="layout layout--col layout--center">
+  <span class="title title--large">Hello, TRMNL!</span>
+</div>
+
+<div class="title_bar">
+  <span class="title">My Plugin</span>
+</div>

data/templates/init/src/half_horizontal.liquid

@@ -1 +1,7 @@
-half horizontal!
+<div class="layout layout--col layout--center">
+  <span class="title title--large">Half horizontal</span>
+</div>
+
+<div class="title_bar">
+  <span class="title">My Plugin</span>
+</div>

data/templates/init/src/half_vertical.liquid

@@ -1 +1,7 @@
-half vertical!
+<div class="layout layout--col layout--center">
+  <span class="title title--large">Half vertical</span>
+</div>
+
+<div class="title_bar">
+  <span class="title">My Plugin</span>
+</div>

data/templates/init/src/quadrant.liquid

@@ -1 +1,7 @@
-quadrant!
+<div class="layout layout--col layout--center">
+  <span class="title title--large">Quadrant</span>
+</div>
+
+<div class="title_bar">
+  <span class="title">My Plugin</span>
+</div>

data/trmnl_preview.gemspec

@@ -21,17 +21,20 @@ Gem::Specification.new do |spec|
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(__dir__) do
-    [
+    files = [
       'bin/**/*',
       'db/**/*',
       'lib/**/*',
-      'templates/**/{*,.*}',
       'web/**/*',
       'CHANGELOG.md',
       'LICENSE.txt',
       'README.md',
       'trmnl_preview.gemspec'
     ].flat_map { |glob| Dir[glob] }
+
+    # FNM_DOTMATCH so the glob descends into the templates' hidden directories
+    # (e.g. .github/) — a plain Dir[] skips them and drops the file from the gem.
+    files + Dir.glob('templates/**/{*,.*}', File::FNM_DOTMATCH)
   end
   spec.bindir = 'bin'
   spec.executables = ['trmnlp']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.8.4
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -319,6 +319,8 @@ files:
 - lib/trmnlp/user_data_assembler.rb
 - lib/trmnlp/version.rb
 - lib/trmnlp/watcher.rb
+- templates/init/.github/workflows/trmnl.yml
+- templates/init/.gitignore
 - templates/init/.trmnlp.yml
 - templates/init/bin/trmnlp
 - templates/init/src/full.liquid