rails-hyperdrive 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19c65882e51a2efb328a453fec5a561af7b9b012e09623f39eba055b7898bcab
-  data.tar.gz: e2bdf0a95fe1ed81db2bb56f0f649c924f502b28a7577f6931778ebb95ca81c0
+  metadata.gz: 65854e72d10acf60fd5140b816d8ee96bc6f573679dd74e7aeb369cbad9f572a
+  data.tar.gz: d86dd2e00fe05e063861b6a408c78dc38809a541cc39fa63a6ab5ca709e88bc3
 SHA512:
-  metadata.gz: e2f083bf83220b970052d44b95c11f6d69b26a58801094cdce349de803b4497983925ba4082d1167e17226d0e5511ac328dc644d71239f7c5694c853f49f6dad
-  data.tar.gz: 955afb3426b981ae68136de0f8f3e1d8ecceb70abcb7a56579b7aaeeb00824915cc273b00244315ba2d49d94a8d0a73bfbe7e68d5c5750a5830a5e1fbaeba52e
+  metadata.gz: a4a279ebaaf70cf2cd43d050d8d031b0ddc45f0e7790e49954dc4f8c96e1a0733c61c3bb4a1ee365ed076992f29a47f00a40707c964328d11f63b5130cd1ce28
+  data.tar.gz: c84c36f0563a52ae2938a998167f2287d68ec586f355794b48c6b79887446fac5cc127f20e0a260613aaeb43f8d9d3187fd198b72a51f3ab7482b20ab5a84f41

data/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-26
+
+### Added
+
+- **ERB templates for guidelines, agents, and commands.** A companion can ship a
+  flat artifact as `<name>.md.erb` directly in its own root
+  (`lib/<gem_name>/hyperdrive/guidelines/`, `agents/`, `commands/`, or an
+  `agents_dir:`/`commands_dir:` override). It renders at discovery against the
+  app's resolved bundle with the same helpers skills use — `gem?`, `any_gem?`,
+  `gem_version`, `canonical_render?` — and installs as `<name>.md`: a
+  guideline's frontmatter is parsed from the render and then stripped, a
+  templated command takes its identity from the rendered stem
+  (`analyze.md.erb` → `/analyze`, prefixed by `command_prefix:` as usual), and
+  the rendered bytes are what the lock hashes, so a re-render is an ordinary
+  upstream delivery through the existing drift, sidecar, and merge machinery.
+  There is no template/content pairing for flat kinds and no separate template
+  root: Claude Code plugins glob `*.md`, so a template is invisible to them.
+  A static `<name>.md` beats a template rendering to the same filename anywhere
+  in the kind's roots, always with a warning; a manifest entry may key the
+  artifact by either spelling (`reviewer.md.erb` or `reviewer.md`), the shipped
+  spelling winning with a warning when both appear, and
+  `rake hyperdrive:manifest:check` fails on that ambiguity. A convention-path
+  guideline template opts a gem in as a companion, like its static twin.
+  Declare a gem-wide `hyperdrive_version: ">= 0.8"` when shipping templated flat
+  artifacts: earlier installers never look for `*.md.erb` outside skill
+  directories, so the fence is what turns their silence into "upgrade
+  rails-hyperdrive to install it".
+- `canonical_render?`, a fourth skill-template ERB helper: `true` in the
+  author-side canonical render (`rake hyperdrive:skills:render`/`check`) and
+  `false` when rendering into an app, so one template can serve both channels
+  where the same content has to read differently — a companion that also ships
+  as a Claude Code plugin, say, whose command spellings differ from the
+  hyperdrive-installed ones. Unlike the bundle predicates it is deterministic in
+  both bindings, so `if`/`else`/`unless` on it is safe. A template using it
+  should declare `hyperdrive_version: ">= 0.8"` in its manifest entry (or
+  gem-wide), so an older installer reports "upgrade rails-hyperdrive" rather
+  than skipping the skill with a template-render failure.
+
 ## [0.7.0] - 2026-08-26
 
 ### Added
@@ -716,7 +754,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `hyperdrive:init` generator that installs architecture skills and auto-discovers
   per-gem skills.
 
-[Unreleased]: https://github.com/rails-hyperdrive/rails-hyperdrive/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/rails-hyperdrive/rails-hyperdrive/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.8.0
 [0.7.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.7.0
 [0.6.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.6.0
 [0.5.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.5.0

data/README.md

@@ -198,7 +198,7 @@ lib/<gem_name>/hyperdrive/guidelines/<name>.md         # guideline (flat file)
 
 `<gem_name>` is your gem's name exactly as published, dashes and all — `rails-hyperdrive-sidekiq` ships guidelines under `lib/rails-hyperdrive-sidekiq/hyperdrive/guidelines/`, not `lib/rails/hyperdrive/sidekiq/`.
 
-Top-level `skills/`, `agents/`, and `commands/` are the tool-agnostic face of your gem — the same sibling layout `.claude/` has, so relative links between them keep resolving once installed. They are readable by skills.sh and plain git-clone consumers as well as hyperdrive, and are scanned once your gem has opted in (below). `lib/<gem_name>/hyperdrive/` is the hyperdrive-specific root: guidelines, and ERB skill templates (`SKILL.md.erb`, which must stay out of `skills/` so raw ERB never reaches generic consumers). Plain skills shipped under it remain scanned as well.
+Top-level `skills/`, `agents/`, and `commands/` are the tool-agnostic face of your gem — the same sibling layout `.claude/` has, so relative links between them keep resolving once installed. They are readable by skills.sh and plain git-clone consumers as well as hyperdrive, and are scanned once your gem has opted in (below). `lib/<gem_name>/hyperdrive/` is the hyperdrive-specific root: guidelines, and ERB skill templates (`SKILL.md.erb`, which must stay out of `skills/` so raw ERB never reaches generic consumers). Plain skills shipped under it remain scanned as well. Guidelines, agents, and commands may ship as `<name>.md.erb` in their own roots — rendered against the app's bundle at discovery and installed as `<name>.md`, with a static file of the same name taking precedence.
 
 Frontmatter is pure skills.sh: only `name` and `description` are read, so a skill repo's content integrates without modification:
 

data/lib/rails/hyperdrive/bundler_artifact_discovery.rb

@@ -88,9 +88,7 @@ module Rails
             next
           end
           manifest = GemManifest.load(spec, warnings: report.warnings)
-          seen = Hash.new { |h, k| h[k] = [] }
-          each_artifact_path(spec, manifest: manifest, report: report) do |path, kind, support_root, key|
-            seen[kind.type] << key
+          seen = each_artifact_path(spec, manifest: manifest, report: report) do |path, kind, support_root, key|
             gate = manifest.gate(kind.type, key)
             artifact = parse(path, source_spec: spec, kind: kind, resolved: resolved,
               report: report, support_root: support_root, gate: gate, key: key, manifest: manifest)
@@ -111,20 +109,27 @@ module Rails
         end
       end
 
-      # Yields each candidate with its kind descriptor and its manifest join
-      # key: a directory-shaped kind's relpath from its root, a flat kind's
-      # filename. Keys are collected before parsing, so a candidate later
-      # dropped (e.g. an ERB render failure) still counts as known to the
-      # manifest.
+      # Yields each candidate with its kind descriptor and the manifest join key
+      # its gating is read under: a directory-shaped kind's relpath from its
+      # root, a flat kind's filename. Returns every key the manifest could have
+      # named a shipped artifact by, collected before parsing so a candidate
+      # later dropped (e.g. an ERB render failure) still counts as known.
       def each_artifact_path(spec, manifest:, report:)
+        seen = Hash.new { |h, k| h[k] = [] }
         InstallLayout.content_kinds.each do |kind|
           if kind.dir_shaped?
-            skill_paths(spec, manifest: manifest, report: report)
-              .each { |path, support_root, rel| yield path, kind, support_root, rel }
+            skill_paths(spec, manifest: manifest, report: report).each do |path, support_root, rel|
+              seen[kind.type] << rel
+              yield path, kind, support_root, rel
+            end
           else
-            flat_paths(spec, kind, manifest: manifest).each { |p| yield p, kind, nil, File.basename(p) }
+            seen[kind.type].concat(flat_keys(spec, kind, manifest: manifest))
+            flat_paths(spec, kind, manifest: manifest, report: report).each do |path|
+              yield path, kind, nil, flat_gate_key(path, kind, manifest, spec, report)
+            end
           end
         end
+        seen
       end
 
       # The staleness signal for gating detached from content: an entry
@@ -212,14 +217,60 @@ module Rails
           "supporting *.md.erb templates; static supporting files ship in the paired content directory"
       end
 
-      # One .md file per artifact, deduped by expanded path so overlapping roots
-      # yield each file once.
-      def flat_paths(spec, kind, manifest:)
+      # One file per artifact: everything shipped, minus the templates a static
+      # file already ships the rendered face of.
+      def flat_paths(spec, kind, manifest:, report:)
+        resolve_flat_ties(flat_candidates(spec, kind, manifest: manifest), report)
+      end
+
+      # Every filename a manifest may key one of the kind's artifacts by: the
+      # name as shipped, plus each template's rendered face. Templates the tie
+      # rule drops are included — the manifest names shipped files, not
+      # surviving ones.
+      def flat_keys(spec, kind, manifest:)
+        flat_candidates(spec, kind, manifest: manifest)
+          .flat_map { |path| [File.basename(path), File.basename(target_path(path))] }
+          .uniq
+      end
+
+      # Deduped by expanded path so overlapping roots yield each file once.
+      def flat_candidates(spec, kind, manifest:)
+        glob = kind.erb ? "{*.md,*.md.erb}" : "*.md"
         artifact_roots(spec, kind, manifest)
-          .flat_map { |root| Dir.glob(File.join(root, "*.md")) }
+          .flat_map { |root| Dir.glob(File.join(root, glob)) }
           .uniq { |path| File.expand_path(path) }
       end
 
+      # A flat kind is identified by its filename, so a static file and a
+      # template rendering to that name are the same artifact anywhere in the
+      # root set; the static one wins, never silently.
+      def resolve_flat_ties(paths, report)
+        paths.group_by { |path| File.basename(target_path(path)) }.flat_map do |face, group|
+          templates, static = group.partition { |path| erb_template?(path) }
+          next group if templates.empty? || static.empty?
+
+          templates.each { |path| report.skip "skip #{path}: #{face} takes precedence" }
+          static
+        end
+      end
+
+      # A templated artifact answers to its shipped *.md.erb name and to the
+      # rendered face it installs as; the exact spelling wins when a manifest
+      # carries both.
+      def flat_gate_key(path, kind, manifest, spec, report)
+        shipped = File.basename(path)
+        face = File.basename(target_path(path))
+        return shipped if face == shipped
+
+        keys = manifest.section_keys(kind.type)
+        return face if keys.include?(face) && !keys.include?(shipped)
+        if keys.include?(shipped) && keys.include?(face)
+          report.warn "#{spec.name}: manifest #{kind.section} keys '#{shipped}' and '#{face}' both gate " \
+                      "'#{face}'; using '#{shipped}'"
+        end
+        shipped
+      end
+
       # The manifest's directory override is searched in addition to the kind's
       # convention roots, never instead of them.
       def artifact_roots(spec, kind, manifest)
@@ -239,7 +290,7 @@ module Rails
 
         convention_root = File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive")
         Dir.glob(File.join(convention_root, "skills", "**", "{SKILL.md,SKILL.md.erb}")).any? ||
-          Dir.glob(File.join(convention_root, "guidelines", "*.md")).any?
+          Dir.glob(File.join(convention_root, "guidelines", "{*.md,*.md.erb}")).any?
       end
 
       def metadata_present?(spec, key)
@@ -348,7 +399,7 @@ module Rails
       # the manifest; the manifest still keys its own entries by the shipped
       # filename.
       def prefixed_stem(path, kind, manifest)
-        stem = File.basename(path, ".md")
+        stem = File.basename(target_path(path), ".md")
         prefix = manifest.name_prefix(kind.type)
         prefix ? "#{prefix}-#{stem}" : stem
       end
@@ -629,6 +680,7 @@ module Rails
       end
 
       private_class_method :each_artifact_path, :warn_unknown_manifest_keys,
+                           :flat_paths, :flat_candidates, :resolve_flat_ties, :flat_gate_key,
                            :artifact_roots, :prefixed_stem, :templates_root,
                            :resolve_same_dir_tie, :pair_with_templates, :warn_template_extras,
                            :opted_in?, :metadata_present?, :notice_skills_sh_content,

data/lib/rails/hyperdrive/install_layout.rb

@@ -22,7 +22,7 @@ module Rails
       # identified and validated, and where each target tool installs it.
       Kind = Struct.new(
         :type, :shape, :section, :key_label, :shipped_label, :dir_key, :prefix_key,
-        :convention_roots, :identity, :frontmatter, :install_body,
+        :convention_roots, :identity, :frontmatter, :install_body, :erb,
         :collision_rewrites_name, :eager, :name_from_dest, :dests,
         keyword_init: true
       ) do
@@ -63,6 +63,7 @@ module Rails
           identity: :frontmatter,
           frontmatter: :required,
           install_body: :verbatim,
+          erb: true,
           collision_rewrites_name: true,
           eager: false,
           name_from_dest: ->(dest) { File.basename(File.dirname(dest)) },
@@ -89,6 +90,7 @@ module Rails
           identity: :frontmatter,
           frontmatter: :required,
           install_body: :strip_frontmatter,
+          erb: true,
           collision_rewrites_name: false,
           eager: true,
           name_from_dest: ->(dest) { File.basename(dest, ".md") },
@@ -111,6 +113,7 @@ module Rails
           identity: :frontmatter,
           frontmatter: :required,
           install_body: :verbatim,
+          erb: true,
           collision_rewrites_name: true,
           eager: false,
           name_from_dest: ->(dest) { File.basename(dest, ".md") },
@@ -128,6 +131,7 @@ module Rails
           identity: :filename_stem,
           frontmatter: :optional,
           install_body: :verbatim,
+          erb: true,
           collision_rewrites_name: false,
           eager: false,
           name_from_dest: ->(dest) { File.basename(dest, ".md") },

data/lib/rails/hyperdrive/manifest_lint.rb

@@ -102,9 +102,14 @@ module Rails
         entries.each do |key, entry|
           next if Array(kind.prefix_key).include?(key)
 
+          face = BundlerArtifactDiscovery.target_path(key)
           unless shipped.include?(key)
             problems << "#{kind.section} entry '#{key}' names no shipped #{kind.shipped_label}"
           end
+          if face != key && entries.key?(face)
+            problems << "#{kind.section} entry '#{key}': '#{face}' keys the same file; keep one spelling"
+          end
+
           unless entry.is_a?(Hash)
             problems << "#{kind.section} entry '#{key}' must be a map of gating keys"
             next
@@ -218,8 +223,9 @@ module Rails
         end
       end
 
+      # Both spellings of a template-shipped file, since either gates it.
       def shipped_flat(repo_spec, kind, manifest)
-        BundlerArtifactDiscovery.flat_paths(repo_spec, kind, manifest: manifest).map { |p| File.basename(p) }
+        BundlerArtifactDiscovery.flat_keys(repo_spec, kind, manifest: manifest)
       end
 
       private_class_method :missing_manifest, :problems_in, :parse_root, :each_entry, :check_section_settings,

data/lib/rails/hyperdrive/skill_template.rb

@@ -3,7 +3,7 @@ require "erb"
 module Rails
   module Hyperdrive
     # Renders a skill's *.md.erb sources against the app's resolved bundle.
-    # The three helpers are the only supported template API, but the binding is
+    # The four helpers are the only supported template API, but the binding is
     # an ordinary object rather than a sandbox: a template runs arbitrary Ruby
     # with the privileges of whoever triggered discovery.
     module SkillTemplate
@@ -27,6 +27,10 @@ module Rails
           version&.to_s
         end
 
+        def canonical_render?
+          false
+        end
+
         def template_binding
           binding
         end
@@ -35,7 +39,9 @@ module Rails
       # Canonical render binding: every gem reads as present at any requested
       # version, so an if/elsif/else contributes only its first branch and
       # templates meant for this render must use additive if blocks. There is
-      # no bundle to resolve against, so gem_version is nil.
+      # no bundle to resolve against, so gem_version is nil. canonical_render?
+      # is the exception: it is deterministic in both bindings, so branching on
+      # it is safe.
       class CanonicalContext
         def gem?(_name, _requirement = nil)
           true
@@ -49,6 +55,10 @@ module Rails
           nil
         end
 
+        def canonical_render?
+          true
+        end
+
         def template_binding
           binding
         end

data/lib/rails/hyperdrive/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Hyperdrive
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-hyperdrive
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Bakaface