rhales 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 441e27aff0e4003c6e0351c6cf065cad3c3348c2aba7059acdfe6e26670df95c
-  data.tar.gz: bb38a8fd9c007c9efd3a69a6f5a1355ecbff4874553d7f63bc8b000e730677b7
+  metadata.gz: 249890f733fb9b88bbabe22bcc327aa5d0422c00ea595e4b67751e335e790feb
+  data.tar.gz: 69259f0ab5cc091cc2c4fab33e3eee13859e28ef789e522119e6702f695155ab
 SHA512:
-  metadata.gz: 0733d8449de842934d86fe0af89fa6dc8b0c345248bda7c11c575f004b2996d1d845d3b90d584e28d919d6db1730bb137627af5471215c4ac8b018db06c6db79
-  data.tar.gz: d8d871a587836562d94a249f5bf1abf9624a30391b7186411f2e167afd5376006d6f8d68132e1958ca0eb59f091a19b976f177f4d1757c494bec7c32164ebd2c
+  metadata.gz: c424d4d348c48686ddb60fe068d2839627c552d94a03a507b9cf54f1d39d11dc4d18aaefccc8731ec0aa8fb79d72ef18ea838460d0e36f5d69b5575d7d15ac3d
+  data.tar.gz: 65139df9054a39981ca7f6fd51818544aca039847d4a1d60521e879c2d542f3ca1f2ca9bbeb030154cc735404882d5ca0ede2fcabe64ef55a8194c622518c963

data/.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        ruby: ['3.4', '3.5']
+        ruby: ['3.2', '3.3', '3.4', '3.5']
 
     steps:
       - uses: actions/checkout@v4
@@ -50,7 +50,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        ruby: ['3.4', '3.5']
+        ruby: ['3.2', '3.3', '3.4', '3.5']
 
     steps:
       - uses: actions/checkout@v4
@@ -77,7 +77,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['3.4', '3.5']
+        ruby: ['3.2', '3.3', '3.4', '3.5']
 
     steps:
       - uses: actions/checkout@v4
@@ -99,7 +99,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['3.4', '3.5']
+        ruby: ['3.2', '3.3', '3.4', '3.5']
 
     steps:
       - uses: actions/checkout@v4

data/.github/workflows/release-gem.yml

@@ -0,0 +1,158 @@
+# Release Gem Workflow
+#
+# Automatically builds and publishes the rhales gem to RubyGems.org when a
+# GitHub release is published with a semantic version tag (vMAJOR.MINOR.PATCH,
+# e.g. v0.6.1, v1.2.3).
+#
+# Follows the canonical RubyGems Trusted Publishing workflow:
+#   https://guides.rubygems.org/trusted-publishing/
+#
+# ============================================================================
+# SETUP INSTRUCTIONS (one-time)
+# ============================================================================
+#
+# This workflow uses RubyGems Trusted Publishing (OIDC). No long-lived API
+# key needs to be stored in GitHub.
+#
+# ----------------------------------------------------------------------------
+# 1. Configure the trusted publisher on RubyGems.org
+# ----------------------------------------------------------------------------
+#
+#   a. Sign in to https://rubygems.org and enable MFA on your account
+#      (required for trusted publishing).
+#
+#   b. Open the gem's trusted publisher page (works for both existing gems
+#      and the first-ever publish):
+#        Existing gem: https://rubygems.org/gems/rhales/trusted_publishers
+#        First publish: https://rubygems.org/profile/oidc/pending_trusted_publishers/new
+#
+#   c. Click "Create" and fill in:
+#        Publisher type:    GitHub Actions
+#        Repository owner:  onetimesecret
+#        Repository name:   rhales
+#        Workflow filename: release-gem.yml
+#        Environment:       rubygems.org   (must match `environment.name` below)
+#
+#   d. Save. RubyGems will now accept short-lived OIDC tokens issued by this
+#      workflow running in this repository.
+#
+# ----------------------------------------------------------------------------
+# 2. Configure the GitHub environment
+# ----------------------------------------------------------------------------
+#
+#   a. In GitHub: Settings -> Environments -> New environment
+#      Name: `rubygems.org`   (must match `environment.name` below)
+#
+#   b. Under "Deployment branches and tags", restrict to tags matching:
+#        v*.*.*
+#      This prevents the environment (and its OIDC token) from being used
+#      from any branch or non-release tag.
+#
+#   c. Optional but recommended: add required reviewers to gate publishes
+#      behind manual approval.
+#
+#   No GitHub secrets are required - OIDC handles authentication.
+#
+# ----------------------------------------------------------------------------
+# 3. Cutting a release
+# ----------------------------------------------------------------------------
+#
+#   a. Bump Rhales::VERSION in lib/rhales/version.rb (semver: MAJOR.MINOR.PATCH).
+#   b. Update CHANGELOG.md and commit on main.
+#   c. On GitHub, draft a Release with tag `vX.Y.Z` (matching the constant)
+#      and publish it. This workflow runs automatically: it verifies the tag
+#      matches the gemspec version, builds the gem, and pushes it.
+#
+# ----------------------------------------------------------------------------
+# Fallback: API key (only if Trusted Publishing isn't an option)
+# ----------------------------------------------------------------------------
+#
+#   1. Create an API key at https://rubygems.org/profile/api_keys with scope
+#      "Push rubygem" restricted to the `rhales` gem.
+#   2. Store it as a repo secret named `RUBYGEMS_API_KEY`.
+#   3. Drop the `id-token: write` permission and `environment:` block, and
+#      replace the `rubygems/release-gem` step with:
+#
+#        - name: Publish to RubyGems
+#          env:
+#            GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+#          run: gem push rhales-*.gem
+#
+# ----------------------------------------------------------------------------
+# Action provenance (SHA pins)
+# ----------------------------------------------------------------------------
+#
+# All third-party actions below are pinned to a full commit SHA, per GitHub's
+# secure-use guidance for release-critical workflows. The accompanying
+# comment records the tag the SHA was resolved from so renovate/dependabot
+# can keep them current.
+#
+#   actions/checkout      - official GitHub action
+#   ruby/setup-ruby       - official Ruby org action (GitHub-verified creator)
+#   rubygems/release-gem  - official RubyGems action for trusted publishing
+#
+# ============================================================================
+
+name: Release Gem
+
+on:
+  release:
+    types: [published]
+
+# Coarse default. Each job re-declares the narrowest permissions it needs.
+permissions:
+  contents: read
+
+# Don't allow two release runs to race - one published tag, one publish.
+concurrency:
+  group: release-gem-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Build and push gem
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    environment:
+      name: rubygems.org
+      url: https://rubygems.org/gems/rhales
+
+    permissions:
+      contents: write   # rubygems/release-gem attaches built .gem to the GitHub release
+      id-token: write   # OIDC token for RubyGems Trusted Publishing
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+        with:
+          bundler-cache: true
+          ruby-version: ruby   # latest stable Ruby installed by setup-ruby
+
+      - name: Verify release tag matches Rhales::VERSION
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          case "${RELEASE_TAG}" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *)
+              echo "Release tag '${RELEASE_TAG}' is not a vMAJOR.MINOR.PATCH semver tag." >&2
+              exit 1
+              ;;
+          esac
+          tag_version="${RELEASE_TAG#v}"
+          gem_version="$(ruby -r ./lib/rhales/version.rb -e 'print Rhales::VERSION')"
+          if [ "${tag_version}" != "${gem_version}" ]; then
+            echo "Release tag ${RELEASE_TAG} (${tag_version}) != Rhales::VERSION (${gem_version})." >&2
+            exit 1
+          fi
+          echo "Releasing rhales ${gem_version} from tag ${RELEASE_TAG}"
+
+      - name: Build and push gem to RubyGems
+        uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0

data/.github/workflows/ruby-lint.yml

@@ -48,7 +48,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        ruby: ['3.4', '3.5']
+        ruby: ['3.2', '3.3', '3.4', '3.5']
         continue-on-error: [true]
 
     steps:

data/.rubocop.yml

@@ -17,7 +17,7 @@ AllCops:
   DisabledByDefault: false # flip to true for a good autocorrect time
   UseCache: true
   MaxFilesInCache: 1000
-  TargetRubyVersion: 3.4
+  TargetRubyVersion: 3.2
   Exclude:
     - 'bin/bundle'
     - 'node_modules/**/*'

data/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-05-25
+
+### Added
+- **Automated gem release workflow** (`.github/workflows/release-gem.yml`):
+  builds and publishes the gem to RubyGems.org via Trusted Publishing
+  (OIDC) whenever a GitHub Release is published with a `vMAJOR.MINOR.PATCH`
+  tag. Verifies the tag matches `Rhales::VERSION` before pushing.
+
+### Changed
+- **Dependencies**: bumped `unicode-emoji` from 4.0.4 to 4.2.0 and
+  `unicode-display_width` from 3.1.4 to 3.2.0. The previous
+  `unicode-emoji` cap of `< Ruby 4.0` broke `bundle install` on Ruby 4.x;
+  4.2.0 lifts that cap.
+- **Gemfile.lock**: platform list normalized via
+  `bundle lock --normalize-platforms` so platform-specific gems no longer
+  trigger setup-ruby warnings on CI.
+
+## [0.6.1] - 2026-05-25
+
+### Added
+- **Server-rendered random tokens example** (`examples/token-loader.rue`):
+  pattern-teaching example showing how to generate per-request data with
+  `SecureRandom.hex` in a Ruby view model, validate a nested
+  `z.array(z.object(...))` shape, and walk it with nested `{{#each}}` blocks
+  that fall through to the current outer item without explicit bindings. The
+  original loader-animation use case is documented as a CSS-only follow-on in
+  the `<logic>` block. (#49)
+
+### Changed
+- **Minimum Ruby version lowered from 3.4 to 3.2** - broader compatibility with stable Ruby releases; CI now exercises 3.2, 3.3, 3.4, and 3.5
+
+### Fixed
+- `{{#each}}` block variable `@last` now correctly returns `true` for the final
+  iteration instead of always `false`. Enables comma-separated output via
+  `{{#unless @last}},{{/unless}}` and similar patterns. `EachContext` now
+  accepts and stores the collection's total length.
+
 ## [0.6.0] - 2026-03-21
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rhales (0.6.0)
+    rhales (0.6.2)
       json_schemer (~> 2)
       logger
       tilt (~> 2)
@@ -153,14 +153,14 @@ GEM
       prettier_print (>= 1.2.0)
     tilt (2.6.1)
     tsort (0.2.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
     yard (0.9.37)
     zeitwerk (2.7.3)
 
 PLATFORMS
-  arm64-darwin-24
+  arm64-darwin
   ruby
 
 DEPENDENCIES
@@ -186,4 +186,4 @@ DEPENDENCIES
   yard (~> 0.9)
 
 BUNDLED WITH
-   2.6.6
+   2.7.2

data/README.md

@@ -12,7 +12,7 @@ Rhales is a **type-safe contract enforcement framework** for server-rendered pag
 - ✅ **External Schema References**: Reference TypeScript schema files via `src` attribute for single-source-of-truth patterns
 - ✅ **Multi-directory Search**: Configure `schema_search_paths` to search multiple directories for shared schemas
 - ✅ **tsx Import Mode**: Bundle external schemas with imports via esbuild (`schema_use_tsx_import`)
-- ✅ **Ruby 3.4+ Required**: Updated minimum Ruby version
+- ✅ **Ruby 3.2+ Supported**: Minimum Ruby version
 
 **v0.5 features:** Schema-first design, type safety, simplified API, clear context layers, schema tooling.
 

data/examples/token-loader.rue

@@ -0,0 +1,119 @@
+<!-- examples/token-loader.rue -->
+
+<!--
+  Example: Server-Rendered Random Tokens with Nested Iteration
+
+  Demonstrates four rhales patterns in one small template:
+
+  1. Generating per-request random data on the server (SecureRandom.hex)
+     and passing it to the template via the client: context, instead of
+     relying on client JavaScript to fill the page in.
+
+  2. Validating a nested-array-of-objects shape with
+     z.array(z.object(...)) in the <schema> block.
+
+  3. Iterating with {{#each}} over a top-level array.
+
+  4. Iterating again inside the outer block to walk a nested array.
+     The inner {{#each}} resolves its variable name against the current
+     outer item first, so no explicit binding (`as |cell|`) or path
+     prefix (`this.glyphs`) is needed.
+
+  Each render produces a different output. The most common use case is
+  a pre-boot loader animated with CSS (see the "Use as a loader" note
+  below), but the same shape applies anywhere you want server-generated
+  per-request decorative data: identicons, correlation IDs displayed on
+  error pages, example IDs in onboarding flows, etc.
+-->
+
+<schema lang="js-zod" window="loaderTokens">
+const schema = z.object({
+  cells: z.array(z.object({
+    glyphs: z.array(z.string().length(1)).length(17)
+  })).length(5)
+});
+</schema>
+
+<template>
+<style nonce="{{nonce}}">
+  .tokens {
+    display: inline-flex;
+    gap: .3rem;
+    font-family: ui-monospace, "SF Mono", Menlo, monospace;
+    letter-spacing: 0.05em;
+  }
+</style>
+
+<div class="tokens">
+  {{#each cells}}<span class="cell">{{#each glyphs}}{{.}}{{/each}}</span>{{/each}}
+</div>
+</template>
+
+<logic>
+# Server-Rendered Random Tokens
+#
+# Backend Usage (Ruby):
+#
+# require 'securerandom'
+#
+# cells = Array.new(5) {
+#   { glyphs: Array.new(17) { SecureRandom.hex(1)[0] } }
+# }
+#
+# view = Rhales::View.new(
+#   request,
+#   client: { cells: cells },
+#   server: { pageTitle: 'Loading...' }
+# )
+#
+# html = view.render('token-loader')
+#
+# Why these patterns:
+#
+# 1. Randomness lives in the view model, not the template. Rhales
+#    templates don't expose Random.new or SecureRandom directly --
+#    generate the data in Ruby and hand it to the template via the
+#    client: context. Templates stay pure-render and the data flow
+#    is explicit.
+#
+# 2. CSPRNG over Kernel#rand. Even for decorative output, SecureRandom
+#    signals intent and avoids questions later about why a templating
+#    layer is pulling from a seeded RNG.
+#
+# 3. Fresh data per cell, not a shared pool. Generating 5 x 17 = 85
+#    fresh glyphs (vs. 17 glyphs shuffled five ways) avoids visible
+#    rhyming between adjacent columns.
+#
+# 4. Nested {{#each}} resolves against the current outer item. Inside
+#    {{#each cells}}, the inner {{#each glyphs}} looks up "glyphs" on
+#    each cell hash automatically -- no need to write {{#each
+#    this.glyphs}} or pass an explicit binding. See
+#    lib/rhales/core/template_engine.rb EachContext#get for the
+#    fallthrough order (current item -> parent context).
+#
+# 5. Cache layer caveat. If a fragment cache wraps the response, the
+#    "fresh on every render" guarantee becomes "fresh per cache miss."
+#    Worst case is the same tokens until the cache TTL expires, which
+#    matches the behavior of a fully static template. For anything
+#    where per-request uniqueness actually matters, exclude this block
+#    from the cache.
+#
+# Use as a loader:
+#
+# The original motivation for this template was a pre-boot SPA loader
+# that "looks like" something is being computed. To wire that up, wrap
+# the output in role="status" with a visually-hidden label so screen
+# readers announce it correctly, and add CSS that scrolls each cell's
+# glyphs vertically before locking onto a final character. The 17
+# glyphs per cell are sized for a 16-step CSS animation with one
+# resting frame:
+#
+#   <div class="tokens" role="status" aria-label="Loading">
+#     ... iteration ...
+#     <span class="visually-hidden">Loading</span>
+#   </div>
+#
+# The animation itself is just CSS keyframes on the iterated spans and
+# is independent of rhales -- the rhales-specific work ends at
+# rendering the markup with fresh random characters per request.
+</logic>

data/lib/rhales/core/template_engine.rb

@@ -202,9 +202,11 @@ module Rhales
       items = get_variable_value(items_var)
 
       if items.respond_to?(:each)
-        items.map.with_index do |item, index|
+        items_array = items.to_a
+        total       = items_array.size
+        items_array.map.with_index do |item, index|
           # Create context for each iteration
-          item_context = create_each_context(item, index, items_var)
+          item_context = create_each_context(item, index, items_var, total)
           engine       = self.class.new('', item_context, partial_resolver: @partial_resolver)
           engine.send(:render_content_nodes, block_content)
         end.join
@@ -312,8 +314,8 @@ module Rhales
     end
 
     # Create context for each iteration
-    def create_each_context(item, index, items_var)
-      EachContext.new(@context, item, index, items_var)
+    def create_each_context(item, index, items_var, total = nil)
+      EachContext.new(@context, item, index, items_var, total)
     end
 
     # HTML escape for XSS protection
@@ -323,13 +325,14 @@ module Rhales
 
     # Context wrapper for {{#each}} iterations
     class EachContext
-      attr_reader :parent_context, :current_item, :current_index, :items_var
+      attr_reader :parent_context, :current_item, :current_index, :items_var, :total
 
-      def initialize(parent_context, current_item, current_index, items_var)
+      def initialize(parent_context, current_item, current_index, items_var, total = nil)
         @parent_context = parent_context
         @current_item   = current_item
         @current_index  = current_index
         @items_var      = items_var
+        @total          = total
       end
 
       def get(variable_name)
@@ -342,8 +345,7 @@ module Rhales
         when '@first'
           return @current_index == 0
         when '@last'
-          # We'd need to know the total length for this
-          return false
+          return @total ? @current_index == @total - 1 : false
         end
 
         # Check if it's a property of the current item

data/lib/rhales/parsers/rue_format_parser.rb

@@ -343,7 +343,7 @@ module Rhales
     end
 
     # Preprocess content to strip XML/HTML comments outside of sections
-    # Uses Ruby 3.4+ pattern matching for robust, secure parsing
+    # Uses Ruby 3.2+ pattern matching for robust, secure parsing
     def preprocess_content(content)
       tokens = tokenize_content(content)
 

data/lib/rhales/version.rb

@@ -5,6 +5,6 @@
 module Rhales
   # Version information for the RSFC gem
   unless defined?(Rhales::VERSION)
-    VERSION = '0.6.0'
+    VERSION = '0.6.2'
   end
 end

data/rhales.gemspec

@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.homepage              = 'https://github.com/onetimesecret/rhales'
   spec.license               = 'MIT'
-  spec.required_ruby_version = '>= 3.4'
+  spec.required_ruby_version = '>= 3.2'
 
   spec.metadata['source_code_uri']       = 'https://github.com/onetimesecret/rhales'
   spec.metadata['changelog_uri']         = 'https://github.com/onetimesecret/rhales/blob/main/CHANGELOG.md'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhales
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.2
 platform: ruby
 authors:
 - delano
@@ -70,6 +70,7 @@ files:
 - ".github/workflows/claude-code-review.yml"
 - ".github/workflows/claude.yml"
 - ".github/workflows/code-smells.yml"
+- ".github/workflows/release-gem.yml"
 - ".github/workflows/ruby-lint.yml"
 - ".github/workflows/yardoc.yml"
 - ".gitignore"
@@ -120,6 +121,7 @@ files:
 - examples/dashboard-with-charts.rue
 - examples/form-with-validation.rue
 - examples/simple-page.rue
+- examples/token-loader.rue
 - examples/vue.rue
 - generate-json-schemas.ts
 - json_schemer_migration_summary.md
@@ -189,14 +191,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Rhales - Server-rendered components with client-side hydration (RSFCs)
 test_files: []