trmnl_preview 0.14.2 → 0.16.0

data/lib/trmnlp/async_callback.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'reporter'
+require_relative 'webhook_payload'
+
+module TRMNLP
+  # TRMNL's async_polling handshake: each poll gives the API a callback url with a new version,
+  # and only a post to the latest version, within 15 minutes, is stored. Answers TRMNL's status and body.
+  class AsyncCallback
+    EXPIRY_SECONDS = 15 * 60
+
+    attr_accessor :server_url
+
+    def initialize(config:, paths:, reporter: Reporter.new)
+      @config = config
+      @paths = paths
+      @reporter = reporter
+      @version = 0
+    end
+
+    def start
+      @version += 1
+      @expires_at = Time.now + EXPIRY_SECONDS
+      "#{server_url}/callback?v=#{@version}"
+    end
+
+    def cancel = @expires_at = nil
+
+    def awaiting? = !@expires_at.nil? && !expired?
+
+    def expired? = !@expires_at.nil? && Time.now > @expires_at
+
+    def call(body, version)
+      refusal = refusal_for(version)
+      return refuse(410, refusal) if refusal
+
+      parsed = JSON.parse(body)
+      payload = WebhookPayload.new(parsed.is_a?(Hash) ? parsed.slice('merge_variables') : parsed)
+      return refuse(422, payload.rejection) if payload.rejection
+
+      store(payload)
+      [200, { status: 'ok' }]
+    rescue JSON::ParserError => e
+      refuse(400, e.message)
+    end
+
+    private
+
+    attr_reader :config, :paths, :reporter
+
+    def refusal_for(version)
+      return 'Strategy is not async_polling' unless config.plugin.async_polling?
+      return 'No pending async request' unless @expires_at
+      return 'Version mismatch' unless version.to_i == @version
+
+      'Async request expired' if expired?
+    end
+
+    def store(payload)
+      cancel
+      payload.size_warning(payload.merge_variables)&.then { report_warning(it) }
+      paths.user_data.dirname.mkpath
+      paths.user_data.write(JSON.generate(payload.merge_variables))
+    end
+
+    def refuse(status, message)
+      report_warning(message)
+      [status, { message: }]
+    end
+
+    def report_warning(message) = reporter.info(reporter.yellow("callback warning: #{message}"))
+  end
+end

data/lib/trmnlp/cli.rb

@@ -72,6 +72,8 @@ module TRMNLP
     end
 
     desc 'lint', 'Check plugin code against TRMNL best practices'
+    method_option :format, type: :string, default: 'text', enum: %w[text json],
+                           desc: 'Report format (text or json)'
     def lint
       # Exit non-zero when issues are found so CI pipelines can gate on it.
       exit(1) unless Commands::Lint.run(options)

data/lib/trmnlp/commands/lint.rb

@@ -2,12 +2,18 @@
 
 require_relative 'base'
 require_relative '../lint'
+require_relative '../lint/diagnostic'
+require 'json'
 
 module TRMNLP
   module Commands
     # Runs the markup best-practice checks and reports their findings.
     class Lint < Base
-      Options = Data.define(:dir, :quiet)
+      Options = Data.define(:dir, :quiet, :format) do
+        def initialize(dir:, quiet:, format: 'text')
+          super(dir:, quiet:, format: format || 'text')
+        end
+      end
 
       def call
         context.validate!
@@ -18,7 +24,10 @@ module TRMNLP
       private
 
       def issues
-        @issues ||= TRMNLP::Lint::CHECKS.flat_map { |check| check.new(source).issues }.uniq
+        @issues ||= TRMNLP::Lint::CHECKS.flat_map do |type|
+          check = type.new(source)
+          check.issues.map { |finding| TRMNLP::Lint::Diagnostic.new(check, source, finding).to_h }
+        end.uniq
       end
 
       def source
@@ -26,6 +35,8 @@ module TRMNLP
       end
 
       def report
+        return reporter.info(JSON.generate(version: 1, passed: issues.empty?, issues:)) if options.format == 'json'
+
         return reporter.info(reporter.green('✓ All checks passed!')) if issues.empty?
 
         reporter.info(reporter.yellow("#{issues.size} issue#{'s' if issues.size > 1} found:\n"))
@@ -34,7 +45,11 @@ module TRMNLP
       end
 
       def report_issue(issue, index)
-        reporter.info("  #{index + 1}. #{issue[:message]}")
+        reporter.info("  #{index + 1}. [#{issue[:rule_id]}] #{issue[:message]}")
+        issue[:locations].each do |location|
+          reporter.info("     #{location[:path]}:#{location[:line]}:#{location[:column]}")
+          reporter.info("       #{location[:snippet]}") unless location[:snippet].to_s.empty?
+        end
         reporter.info("     Learn more: #{issue[:learn_more]}") if issue[:learn_more]
       end
     end

data/lib/trmnlp/commands/serve.rb

@@ -23,6 +23,7 @@ module TRMNLP
         App.set(:browser_pool, BrowserPool.new(driver_factory: FirefoxDriver.method(:build)))
         App.set(:bind, options.bind)
         App.set(:port, options.port)
+        context.async_callback.server_url = "http://#{callback_host}:#{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')
@@ -34,6 +35,8 @@ module TRMNLP
 
       private
 
+      def callback_host = options.bind == '0.0.0.0' ? 'localhost' : options.bind
+
       # Codespaces forwards the dev port through a proxy whose Host header Sinatra rejects.
       def codespaces? = ENV['CODESPACES'] == 'true'
 

data/lib/trmnlp/config/plugin.rb

@@ -6,6 +6,7 @@ require 'yaml'
 
 require_relative '../errors'
 require_relative '../framework_version'
+require_relative '../select_field_choices'
 
 module TRMNLP
   class Config
@@ -31,19 +32,24 @@ module TRMNLP
       def polling? = strategy == 'polling'
       def webhook? = strategy == 'webhook'
       def static? = strategy == 'static'
+      def async_polling? = strategy == 'async_polling'
+      def plugin_merge? = strategy == 'plugin_merge'
 
-      def polling_urls(extra_variables: {})
-        # allow project-level config to override
-        urls = project_config.user_data_overrides.dig('trmnl', 'plugin_settings',
-                                                      'polling_url') || @config['polling_url']
+      # TRMNL transforms a webhook post as it arrives, and never transforms async_polling or plugin_merge data.
+      def transforms_on_render? = !(webhook? || async_polling? || plugin_merge?)
 
-        return [] if urls.nil?
+      # One url per line, as TRMNL reads them: CR or LF, squished, blank lines dropped.
+      def polling_urls(extra_variables: {})
+        return [] if polling_url_text.nil?
 
-        with_custom_fields(urls, extra_variables:).strip.split("\n")
+        with_custom_fields(polling_url_text, extra_variables:).tr("\r", "\n").split("\n")
+                                                              .map { it.gsub(/\s+/, ' ').strip }.reject(&:empty?)
       end
 
-      # for {{ trmnl }}
-      def polling_url_text = polling_urls.join("\r\n")
+      # Unrendered, as TRMNL exposes it to markup. A project-level override wins.
+      def polling_url_text
+        project_config.user_data_overrides.dig('trmnl', 'plugin_settings', 'polling_url') || @config['polling_url']
+      end
 
       def polling_verb = @config['polling_verb'] || 'GET'
 
@@ -55,9 +61,6 @@ module TRMNLP
         string_to_hash(rendered)
       end
 
-      # for {{ trmnl }}
-      def polling_headers_encoded = polling_headers.map { |k, v| "#{k}=#{v}" }.join('&')
-
       def polling_body(extra_variables: {}) = with_custom_fields(@config['polling_body'] || '', extra_variables:)
 
       def dark_mode = @config['dark_mode'] || 'no'
@@ -101,6 +104,23 @@ module TRMNLP
       # Config::Project#custom_fields, which holds the field *values*.
       def custom_field_definitions = @config['custom_fields'] || []
 
+      # What TRMNL renders with: a select's label saved as its value, a blank value as its default.
+      def custom_fields_values
+        values = project_config.custom_fields_with_env.to_h { |keyname, value| [keyname, stored_value(keyname, value)] }
+        custom_field_defaults.merge(values) { |_, default, value| value.to_s.strip.empty? ? default : value }
+      end
+
+      # Fields a polling url needs that are still blank. TRMNL skips polling until they are filled in.
+      def missing_required_fields
+        url = polling_url_text.to_s
+        return [] if url.strip.empty?
+
+        values = custom_fields_values
+        custom_field_definitions.reject { it['optional'] || blank_is_a_valid_answer?(it) }
+                                .map { it['keyname'] }
+                                .select { interpolated_without_default?(url, it) && values[it].to_s.strip.empty? }
+      end
+
       # The raw parsed settings.yml hash. Most callers want the semantic
       # readers above; `trmnlp lint` needs the uninterpreted values because
       # it searches the raw {{ }} templates the semantic readers render away.
@@ -111,7 +131,27 @@ module TRMNLP
       attr_reader :paths, :project_config
 
       def with_custom_fields(value, extra_variables: {})
-        project_config.with_custom_fields(value, extra_variables:)
+        project_config.with_custom_fields(value, values: custom_fields_values, extra_variables:)
+      end
+
+      def custom_field_defaults
+        custom_field_definitions.to_h { [it['keyname'], it['default']] }.reject { |_, default| default.to_s.empty? }
+      end
+
+      def stored_value(keyname, value)
+        field = custom_field_definitions.find { it['keyname'] == keyname && it['field_type'] == 'select' }
+        field ? SelectFieldChoices.new(field).stored_value(value) : value
+      end
+
+      def interpolated_without_default?(url, keyname)
+        url.scan(/\{\{-?\s*(?:trmnl\.plugin_settings\.custom_fields_values\.)?#{Regexp.escape(keyname)}\b([^}]*)/)
+           .any? { |(filters)| !filters.match?(/\|\s*default\s*:/) }
+      end
+
+      # A select's empty option is an answer, not a gap.
+      def blank_is_a_valid_answer?(field)
+        field['field_type'] == 'boolean' || !field['default'].to_s.strip.empty? || field['conditional_validation'] ||
+          Array(field['options']).any? { it.is_a?(Hash) ? it.values.first.to_s.strip.empty? : it.to_s.strip.empty? }
       end
 
       # Mirrors the hosted service's Plugins::Helpers::Transformer#string_to_hash.

data/lib/trmnlp/config/project.rb

@@ -26,7 +26,12 @@ module TRMNLP
         raise InvalidConfig, ".trmnlp.yml is not valid YAML: #{e.message}"
       end
 
-      def user_filters = @config['custom_filters'] || []
+      def user_filter_modules
+        (@config['custom_filters'] || []).map do |module_name, relative_path|
+          require paths.root_dir.join(relative_path)
+          Object.const_get(module_name)
+        end
+      end
 
       def live_render? = !watch_paths.empty?
 
@@ -36,13 +41,18 @@ module TRMNLP
 
       def custom_fields = @config.fetch('custom_fields', {}).transform_values { |v| stringify_field_value(v) }
 
+      # Values with {{ env.X }} filled in, standing in for what a user types into TRMNL's form.
+      def custom_fields_with_env = custom_fields.transform_values { |v| with_env(v) }
+
       def user_data_overrides = @config['variables'] || {}
 
+      # plugin_merge references ("<keyname>_<id>") mapped to the trmnlp project directories that stand in for them.
+      def merged_plugins = @config['merged_plugins'] || {}
+
       # extra_variables lets the poller inject live values (e.g.
       # oauth_access_token) into the same custom-field render.
-      def with_custom_fields(value, extra_variables: {})
-        custom_fields_with_env = custom_fields.transform_values { |v| with_env(v) }
-        parse_liquid(value).render(custom_fields_with_env.merge(extra_variables))
+      def with_custom_fields(value, values:, extra_variables: {})
+        parse_liquid(value).render(values.merge(extra_variables))
       end
 
       def time_zone = @config['time_zone'] || 'UTC'

data/lib/trmnlp/context.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'async_callback'
 require_relative 'config'
 require_relative 'paths'
 require_relative 'poller'
@@ -8,6 +9,7 @@ require_relative 'reporter'
 require_relative 'transform_pipeline'
 require_relative 'user_data_assembler'
 require_relative 'watcher'
+require_relative 'webhook_receiver'
 
 module TRMNLP
   class Context
@@ -22,7 +24,12 @@ module TRMNLP
     # Context is the composition root: it wires and memoizes the runtime
     # object graph. Callers take the collaborator they need and talk to it
     # directly — Context does not forward methods on their behalf.
-    def poller = @poller ||= Poller.new(config:, paths:, oauth_session:, reporter:)
+    def poller
+      @poller ||= Poller.new(config:, paths:, oauth_session:, reporter:, async_callback:,
+                             trmnl_variables: -> { user_data_assembler.polling_variables })
+    end
+
+    def async_callback = @async_callback ||= AsyncCallback.new(config:, paths:, reporter:)
 
     def oauth_session
       @oauth_session ||= begin
@@ -34,10 +41,18 @@ module TRMNLP
     end
 
     def transform_pipeline = @transform_pipeline ||= TransformPipeline.new(config:, paths:, reporter:)
-    def user_data_assembler = @user_data_assembler ||= UserDataAssembler.new(config:, paths:, transform_pipeline:)
+
+    def user_data_assembler
+      @user_data_assembler ||= UserDataAssembler.new(config:, paths:, transform_pipeline:, oauth_session:)
+    end
+
     def renderer = @renderer ||= Renderer.new(config:, paths:, user_data_assembler:)
     def watcher = @watcher ||= Watcher.new(config:, user_data_assembler:, transform_pipeline:, reporter:)
 
+    def webhook_receiver
+      @webhook_receiver ||= WebhookReceiver.new(paths:, transform_pipeline:, user_data_assembler:, reporter:)
+    end
+
     def validate!
       raise NotAPlugin, "not a plugin directory (did not find #{paths.trmnlp_config})" unless paths.valid?
     end

data/lib/trmnlp/firefox_driver.rb

@@ -18,9 +18,6 @@ module TRMNLP
       Selenium::WebDriver::Firefox::Options.new.tap do |opts|
         opts.add_argument('--headless')
         opts.add_argument('--disable-web-security')
-        # Subpixel antialiasing colour-fringes badly when quantized to 1-bit e-ink.
-        opts.add_preference('gfx.text.disable-aa', true)
-        opts.add_preference('gfx.text.subpixel-position.force-disabled', true)
       end
     end
   end

data/lib/trmnlp/framework_version.rb

@@ -12,6 +12,8 @@ module TRMNLP
     include Comparable
 
     DEFAULT_ASSET_HOST = 'https://trmnl.com'
+    # Framework::Themes::NAMES_BY_ID in trmnl-framework.
+    THEMES = { 'black-and-yellow' => 'Black and Yellow', 'dark' => 'Dark', 'white-and-red' => 'White and Red' }.freeze
     DATA_PATH = File.expand_path('../../db/data/framework_versions.yml', __dir__)
     # DATA_PATH holds a copy of this file, refreshed by `rake framework:sync`.
     MANIFEST_URL = 'https://raw.githubusercontent.com/usetrmnl/trmnl-framework/main/db/data/framework_versions.yml'
@@ -80,6 +82,13 @@ module TRMNLP
 
     def js_url = "#{@asset_host}/js/#{number}/plugins.js"
 
+    # Versions before 3.2.0 publish no themes, so the theme class stays inert there, as on TRMNL.
+    def theme_css_url(theme)
+      return unless THEMES.include?(theme) && Gem::Version.new(number) >= Gem::Version.new('3.2.0')
+
+      "#{@asset_host}/css/#{number}/themes/#{theme}-theme.css"
+    end
+
     def ==(other) = other.is_a?(self.class) && number == other.number
 
     def <=>(other)

data/lib/trmnlp/image_quantizer.rb

@@ -5,12 +5,14 @@ require 'tempfile'
 require 'fileutils'
 
 module TRMNLP
+  # TRMNL's Converter::MagickWrapper steps: a page dithers only when it asks for `image-dither`.
   class ImageQuantizer
     MIN_DEPTH = 1
     MAX_DEPTH = 8
 
-    def initialize(depth:)
+    def initialize(depth:, dither:)
       @depth = clamp(depth)
+      @dither = dither
     end
 
     def call(path)
@@ -25,32 +27,43 @@ module TRMNLP
     def quantize(src, dst)
       MiniMagick.convert do |m|
         m << src
-        m.colorspace 'Gray'
-        m.dither 'FloydSteinberg'
-        apply_depth(m)
+        @dither ? quantize_with_dither(m) : quantize_without_dither(m)
+        m.alpha 'off'
         m.depth @depth
-        m.define "png:bit-depth=#{@depth}"
+        m.type 'Palette'
+        m.define 'png:compression-level=9'
         m.strip
         m << dst
       end
     end
 
-    def apply_depth(m)
+    def quantize_without_dither(m)
       if @depth == 1
-        # NOTE: 1-bit only has black/white, so a halftone remap simulates gray
-        # via dithering patterns. Skipping this collapses photos to pure
-        # silhouettes.
-        m.remap 'pattern:gray50'
-        m.posterize 2
+        m.monochrome
         m.colors 2
-        m.type 'Bilevel'
       else
-        levels = 2**@depth
-        m.posterize levels
-        m.colors levels
+        m.colorspace 'Gray'
+        m.dither 'None'
+        m.posterize gray_level_count
       end
     end
 
+    def quantize_with_dither(m)
+      case @depth
+      when 1
+        m.dither 'FloydSteinberg'
+        m.remap 'pattern:gray50'
+      when 8
+        m.type 'Grayscale'
+      else
+        m.colorspace 'Gray'
+        m.dither 'FloydSteinberg'
+        m.posterize gray_level_count
+      end
+    end
+
+    def gray_level_count = 2**@depth
+
     def clamp(depth)
       [[depth.to_i, MIN_DEPTH].max, MAX_DEPTH].min
     end

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

@@ -19,9 +19,14 @@ module TRMNLP
         UNREACHABLE = [SocketError, Net::OpenTimeout, Net::ReadTimeout,
                        Errno::ECONNREFUSED, Errno::EHOSTUNREACH, OpenSSL::SSL::SSLError].freeze
 
+        attr_reader :unreachable_urls
+
         private
 
-        def pass? = static_image_urls.all? { |url| reachable?(url) }
+        def pass?
+          @unreachable_urls = static_image_urls.reject { |url| reachable?(url) }
+          unreachable_urls.empty?
+        end
 
         def static_image_urls
           source.all_markup

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

@@ -1,25 +1,32 @@
 # frozen_string_literal: true
 
 require_relative '../check'
+require 'crass'
+require 'nokogiri'
 
 module TRMNLP
   module Lint
     module Checks
       class LimitedInlineStyles < Check
         MAX_INLINE_STYLES = 6
-        PROPERTIES = %w[
-          justify-content padding margin background-color
-          border-radius text-align object-fit font-size
-        ].freeze
         MESSAGE = 'Markup uses too many inline styles, add more native Framework classes.'
         LEARN_MORE = 'https://help.trmnl.com/en/articles/11395668-recipe-best-practices#h_3a3eab0712'
 
         private
 
         def pass?
-          count = PROPERTIES.sum { |property| source.all_markup.scan(property).size }
+          count = Nokogiri::HTML.fragment(markup_without_liquid_comments).css('[style]').sum do |element|
+            # Count Liquid output as a CSS value and drop Liquid tags, so every
+            # branch's declarations count without evaluating the template.
+            css = element['style'].gsub(/\{\{.*?\}\}/m, 'var(--trmnlp-liquid)').gsub(/\{%.*?%\}/m, '')
+            Crass.parse_properties(css).count { |token| token[:node] == :property }
+          end
           count <= MAX_INLINE_STYLES
         end
+
+        def markup_without_liquid_comments
+          source.all_markup.gsub(/\{%-?\s*comment\s*-?%\}.*?\{%-?\s*endcomment\s*-?%\}/m, '')
+        end
       end
     end
   end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports markup that uses a filter only .trmnlp.yml custom_filters defines.
+      class NoCustomFilters < Check
+        def self.usage_pattern(filter_name) = /\{[{%](?:(?![}%]\}).)*?\|\s*#{Regexp.escape(filter_name)}\b/m
+
+        def issues
+          used_filter_names.map do |name|
+            { message: "Filter '#{name}' comes from custom_filters in .trmnlp.yml, which TRMNL does not load. " \
+                       'TRMNL outputs the value unfiltered; use a built-in filter or the transform instead.' }
+          end
+        end
+
+        private
+
+        def used_filter_names
+          source.local_only_filter_names.select { |name| source.all_markup.match?(self.class.usage_pattern(name)) }
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/diagnostic.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module Lint
+    # Adds reporting metadata without changing a check's existing #issues API.
+    # Rule IDs are the snake_case check names and are part of the report contract.
+    class Diagnostic
+      SETTINGS_KEYS = {
+        'title_casing' => 'name', 'title_length' => 'name',
+        'description_length' => 'description', 'recipe_overview_length' => 'recipe_overview'
+      }.freeze
+      MARKUP_PATTERNS = {
+        'no_async_functions' => /async function/i,
+        'no_opacity' => Checks::NoOpacity::PATTERN,
+        'no_size_classes' => Checks::NoSizeClasses::PATTERN,
+        'waits_for_dom_load' => Regexp.new(Regexp.union(Checks::WaitsForDomLoad::FORBIDDEN).source, Regexp::IGNORECASE),
+        'limited_inline_styles' => /\sstyle\s*=/i,
+        'highcharts_animations_disabled' => /highcharts/i,
+        'highcharts_elements_unique' => /highcharts/i
+      }.freeze
+
+      def initialize(check, source, finding)
+        @check = check
+        @source = source
+        @finding = finding
+      end
+
+      def to_h
+        finding.merge(rule_id:, severity: 'error', locations: locations.uniq)
+      end
+
+      private
+
+      attr_reader :check, :source, :finding
+
+      def rule_id
+        check.class.name.split('::').last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+
+      def locations
+        return source.yaml_location('src/settings.yml', SETTINGS_KEYS[rule_id]) if SETTINGS_KEYS.key?(rule_id)
+        return source.locations(MARKUP_PATTERNS[rule_id]) if MARKUP_PATTERNS.key?(rule_id)
+
+        case rule_id
+        when 'arbitrary_values_in_range' then class_locations
+        when 'layouts_have_content' then empty_view_locations
+        when 'form_fields_valid' then form_field_locations
+        when 'custom_fields_used' then project_field_locations
+        when 'no_custom_filters' then custom_filter_locations
+        when 'image_links_reachable' then source.locations(Regexp.union(check.unreachable_urls))
+        else []
+        end
+      end
+
+      def class_locations
+        css_class = finding[:message][/\A'([^']+)'/, 1]
+        css_class ? source.locations(Regexp.new(Regexp.escape(css_class))) : []
+      end
+
+      def custom_filter_locations
+        source.locations(Checks::NoCustomFilters.usage_pattern(finding[:message][/Filter '([^']+)'/, 1]))
+      end
+
+      def empty_view_locations
+        return [] if source.shared_markup.length >= Checks::LayoutsHaveContent::MIN_CONTENT_LENGTH
+
+        source.view_markup.filter_map do |view, markup|
+          if markup.length < Checks::LayoutsHaveContent::MIN_CONTENT_LENGTH
+            { path: "src/#{view}.liquid", line: 1, column: 1, snippet: markup }
+          end
+        end
+      end
+
+      def form_field_locations
+        warning = finding[:message].split(' — ', 2).last
+        source.custom_field_definitions.each_with_index.flat_map do |field, index|
+          if FormField.validate(field).include?(warning)
+            source.yaml_location('src/settings.yml', 'custom_fields', index)
+          else
+            []
+          end
+        end
+      end
+
+      def project_field_locations
+        key = finding[:message][/Custom field '([^']+)'/, 1]
+        return [] unless key
+
+        # Project custom-field values can contain credentials. Show the key,
+        # but never echo its value into terminal output or CI artifacts.
+        source.yaml_location('.trmnlp.yml', 'custom_fields', key).map do |location|
+          location.merge(snippet: "#{key}: [value omitted]")
+        end
+      end
+    end
+  end
+end