trmnl_preview 0.8.1 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f80ac8d03e9b67e4ea6c7f18e8cd7745a76c910e9801f910662cc46b5661eb0
-  data.tar.gz: 1022cfae134c303ba7d00201d2d6ca7acb7c23c927371585b9e63a00fa28bfa2
+  metadata.gz: c021076f55f8b5d150e65e2202c5bc978e8709684ee4d9bf27c0b7ec8e0b59b8
+  data.tar.gz: daa5e5734d9b1e3d755b789b0081916e53ce6c0a3cdd6d75e5276335ad2dae83
 SHA512:
-  metadata.gz: 6667ad132d9b601073db2010c524f8322e6a7fd2b5425d248cf3a53398166d1f579171e8c1142da146247f7fcb96192c50c7fa0e8d9158797bc98d7bc9755eb2
-  data.tar.gz: 189d830c8ee5b2ed2ccd2006ef1fda9c6dadd258488a74d4925ac4476762c581fd4df3961fb94f771ff0943f3ba57cd62d0294cff6e5e1c5f79558c763d534a1
+  metadata.gz: d422c11366ba16381be6765dfb36a25e2a662db4e9da3f3b08b780bbabbd94338d65f0f75bf6cbb82a0aa51fee8660886e5cd14203ccfbd2145539a617823559
+  data.tar.gz: 87b5bb57b023748ecc9412e13059801a755e6d0d03c82f27aaacc2077c119ed4386e28fba8a3a4f62ee47b783d4c92e49905d1a47fb29e2f8a93da7caddc563d

data/CHANGELOG.md

@@ -1,6 +1,18 @@
 
 # Changelog
 
+## 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)
+- Cleanup and minor improvements
+
 ## 0.8.1
 
 ### Added

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 |
@@ -111,7 +117,7 @@ trmnlp build --png --color-depth 2
 | `--png` | Render a PNG per view alongside the HTML |
 | `--width` | PNG width in pixels (default 800) |
 | `--height` | PNG height in pixels (default 480) |
-| `--color-depth` | PNG bit depth — 1, 2, or 4 — overriding the markup |
+| `--color-depth` | PNG bit depth — 1-8 — overriding the markup |
 
 `--width`, `--height`, and `--color-depth` apply only with `--png`. PNG rendering needs Firefox and ImageMagick installed; plain `trmnlp build` needs neither.
 
@@ -121,6 +127,56 @@ 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.
 
+## Continuous Integration
+
+`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
+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 }}
+```
+
+The `lint` job gates every pull request — `trmnlp lint` exits non-zero on
+issues, so a failing check blocks the merge. The `push` job uploads to TRMNL
+only on `main`.
+
+> **Make sure `src/settings.yml` has an `id`.** `trmnlp push` updates the
+> plugin with that id; without one it creates a *new* plugin on every run.
+> Projects made with `trmnlp clone` or `trmnlp pull` already have it.
+
 ## 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.
@@ -336,6 +392,21 @@ bin/rake
 
 Specs run under SimpleCov; a coverage report is written to `coverage/`.
 
+## Releasing
+
+Releases are automated. The [`Release` workflow](.github/workflows/release.yaml)
+fires whenever `lib/trmnlp/version.rb` changes on `main`, then tags the commit,
+publishes the gem to RubyGems, and pushes the multi-arch Docker image. Each step
+is idempotent, so the workflow is safe to re-run after a partial failure.
+
+To cut a release:
+
+1. Bump the version in `lib/trmnlp/version.rb`.
+2. Run `bundle install` so `Gemfile.lock` picks up the new version.
+3. Commit and merge to `main` — the workflow does the rest.
+
+By convention, add a matching `CHANGELOG.md` entry in the same change.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/usetrmnl/trmnlp.

data/lib/trmnlp/cli.rb

@@ -22,7 +22,7 @@ module TRMNLP
     method_option :png, type: :boolean, default: false, desc: 'Also render a PNG per view'
     method_option :width, type: :numeric, desc: 'PNG width in pixels (with --png)'
     method_option :height, type: :numeric, desc: 'PNG height in pixels (with --png)'
-    method_option :color_depth, type: :numeric, desc: 'PNG bit depth: 1, 2, or 4 (with --png)'
+    method_option :color_depth, type: :numeric, desc: 'PNG bit depth: 1-8 (with --png)'
     def build
       Commands::Build.run(options)
     end
@@ -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/framework_version.rb

@@ -44,9 +44,13 @@ module TRMNLP
 
     def pinned? = @pinned
 
-    def css_url = "#{@asset_host}/css/#{path_segment}/plugins.css"
+    # Both a pinned and an unpinned ("latest") version resolve to a
+    # concrete release here — #number is never the literal "latest" — so a
+    # local preview renders the same bundle as the hosted service instead
+    # of drifting onto a new release the moment one ships.
+    def css_url = "#{@asset_host}/css/#{number}/plugins.css"
 
-    def js_url = "#{@asset_host}/js/#{path_segment}/plugins.js"
+    def js_url = "#{@asset_host}/js/#{number}/plugins.js"
 
     def ==(other) = other.is_a?(self.class) && number == other.number
 
@@ -59,11 +63,5 @@ module TRMNLP
     def as_json(*) = number
 
     def to_s = number
-
-    private
-
-    # When pinned, requests assets at /css/<version>/plugins.css to lock
-    # behavior; otherwise hit /css/latest/ for live updates.
-    def path_segment = pinned? ? @number : 'latest'
   end
 end

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

@@ -24,8 +24,8 @@ module TRMNLP
         def pass? = static_image_urls.all? { |url| reachable?(url) }
 
         def static_image_urls
-          source.view_markup.values
-                .flat_map { |html| html.scan(/<img[^>]+src\s*=\s*["']([^"']+)["']/i).flatten }
+          source.all_markup
+                .scan(/<img[^>]+src\s*=\s*["']([^"']+)["']/i).flatten
                 .map(&:strip)
                 .reject { |src| src.empty? || src.include?('{{') || src.start_with?('data:') }
         end

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

@@ -6,7 +6,8 @@ module TRMNLP
   module Lint
     module Checks
       class WaitsForDomLoad < Check
-        MESSAGE = 'JavaScript should listen for the DOMContentLoaded event, not window.onLoad()'
+        MESSAGE = 'JavaScript should listen for the DOMContentLoaded event, ' \
+                  'not window.onload or window.addEventListener("load")'
         LEARN_MORE = 'https://help.trmnl.com/en/articles/9510536-private-plugins#h_db7030f8b8'
         FORBIDDEN = ['window.onload', 'window.addeventlistener("load")',
                      "window.addeventlistener('load')"].freeze

data/lib/trmnlp/renderer.rb

@@ -72,7 +72,7 @@ module TRMNLP
       end
     end
 
-    # bindings must match the `GET /render/{view}.html` route in app.rb
+    # ivars must match the @-references in web/views/render_html.erb
     class TemplateBinding
       def initialize(renderer, view, params)
         @view = view

data/lib/trmnlp/transform_backend/http.rb

@@ -59,9 +59,7 @@ module TRMNLP
         TransformClient::Result.new(
           stdout: parsed['stdout'] || '',
           stderr: parsed['stderr'] || '',
-          # Fall back to stdout for daemons that haven't been upgraded to
-          # the separate `output` channel yet.
-          output: (parsed['output'].to_s.empty? ? parsed['stdout'] : parsed['output']).to_s,
+          output: parsed['output'].to_s,
           exit_code: parsed['exit_code'] || 0,
           duration_ms: parsed['duration_ms'] || 0,
           error: parsed['error']

data/lib/trmnlp/transform_backend/wrapper.rb

@@ -9,8 +9,10 @@ module TRMNLP
     # 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.
+    # Mirrors the hosted serverless runtime's code-wrapping behavior,
+    # parameterized on the per-backend output sink. PHP additionally
+    # carries a leading `<?php` tag the file-based Subprocess path
+    # needs; the daemon tolerates it, so parity holds.
     #
     # NOTE: `output_sink` is spliced verbatim into the generated script as
     # executable code. It MUST be trmnlp-generated (see Subprocess#sink_for

data/lib/trmnlp/user_data_assembler.rb

@@ -17,9 +17,9 @@ module TRMNLP
 
     # 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.
+    # then piped through the transform. The whole trmnl namespace is
+    # re-applied after the transform so it survives even when the
+    # transform doesn't pass it through.
     def call(device: {})
       namespace = base_trmnl_data(device:)
       merged = assemble(namespace)

data/lib/trmnlp/version.rb

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

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.1
+  version: 0.8.3
 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