rails-hyperdrive 0.6.0 → 0.8.0

data/lib/rails/hyperdrive/bundler_artifact_discovery.rb

@@ -1,7 +1,9 @@
 require "yaml"
 require "bundler"
 require "rails/hyperdrive/gem_manifest"
+require "rails/hyperdrive/install_layout"
 require "rails/hyperdrive/skill_template"
+require "rails/hyperdrive/version"
 
 module Rails
   module Hyperdrive
@@ -31,33 +33,72 @@ module Rails
         end
       end
 
+      # Everything one discovery walk collects, passed in so a caller reads
+      # back only what it needs. `skips` is the subset of `warnings` that
+      # dropped shipped content; everything else is advisory and installed.
+      # `bundled_gems` and `skipped_gems` report the walk itself: every gem
+      # seen, and every gem that lost at least one artifact to a hard skip.
+      Report = Struct.new(:warnings, :skips, :notices, :fence_warnings, :bundled_gems, :skipped_gems,
+        keyword_init: true) do
+        def initialize(**kw)
+          super(**{ warnings: [], skips: [], notices: [], fence_warnings: [],
+                    bundled_gems: [], skipped_gems: [] }.merge(kw))
+        end
+
+        def warn(message)
+          warnings << message
+        end
+
+        def skip(message)
+          warnings << message
+          skips << message
+        end
+
+        # Version-fence skips are also carried on their own, for surfaces that
+        # print nothing else about discovery.
+        def fence(message)
+          skip(message)
+          fence_warnings << message
+        end
+
+        def advisories
+          warnings - skips
+        end
+
+        def mark_skipped_gem(name)
+          skipped_gems << name unless skipped_gems.include?(name)
+        end
+      end
+
       module_function
 
-      # Non-fatal problems are appended to `warnings` and the artifact is
-      # dropped; discovery never raises. A gem that has not opted in as a
-      # companion is never scanned — its skills.sh content is only reported
-      # through `notices`.
-      def discover(specs: nil, warnings: [], enabled_gems: [], notices: [])
+      # Non-fatal problems are reported and the artifact is dropped; discovery
+      # never raises. A gem that has not opted in as a companion is never
+      # scanned — its skills.sh content is only reported through `notices`.
+      def discover(specs: nil, enabled_gems: [], report: Report.new)
         specs ||= safe_bundler_specs
         enabled = Array(enabled_gems).map(&:to_s)
         resolved = specs.each_with_object({}) { |s, h| h[s.name.to_s] = s.version }
 
         candidates = []
         specs.each do |spec|
+          report.bundled_gems << spec.name.to_s
           unless opted_in?(spec, enabled_gems: enabled)
-            notice_skills_sh_content(spec, notices: notices)
+            notice_skills_sh_content(spec, report: report)
             next
           end
-          manifest = GemManifest.load(spec, warnings: warnings)
-          seen = { skill: [], guideline: [] }
-          each_artifact_path(spec, warnings: warnings) do |path, type, support_root, key|
-            seen[type] << key
-            gate = type == :skill ? manifest.skill_gate(key) : manifest.guideline_gate(key)
-            artifact = parse(path, source_spec: spec, type: type, resolved: resolved,
-              warnings: warnings, support_root: support_root, gate: gate)
-            candidates << artifact if artifact
+          manifest = GemManifest.load(spec, warnings: report.warnings)
+          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)
+            if artifact.is_a?(Artifact)
+              candidates << artifact
+            elsif artifact != :gate_miss
+              report.mark_skipped_gem(spec.name.to_s)
+            end
           end
-          warn_unknown_manifest_keys(manifest, spec, seen, warnings)
+          warn_unknown_manifest_keys(manifest, spec, seen, report)
         end
 
         # Collapse same-name variants within one source gem (highest
@@ -68,34 +109,41 @@ module Rails
         end
       end
 
-      # Yields each candidate with its manifest join key: a skill's relpath
-      # from its skills root, a guideline'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.
-      def each_artifact_path(spec, warnings: [])
-        skill_paths(spec, warnings: warnings).each { |path, support_root, rel| yield path, :skill, support_root, rel }
-        guideline_paths(spec).each { |p| yield p, :guideline, nil, File.basename(p) }
+      # 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 do |path, support_root, rel|
+              seen[kind.type] << rel
+              yield path, kind, support_root, rel
+            end
+          else
+            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
-      # matching nothing means a renamed or removed skill dir/guideline.
-      def warn_unknown_manifest_keys(manifest, spec, seen, warnings)
-        (manifest.skill_keys - seen[:skill]).each do |key|
-          warnings << "#{spec.name}: manifest skills entry '#{key}' names no shipped skill directory"
-        end
-        (manifest.guideline_keys - seen[:guideline]).each do |key|
-          warnings << "#{spec.name}: manifest guidelines entry '#{key}' names no shipped guideline"
+      # matching nothing means a renamed or removed artifact.
+      def warn_unknown_manifest_keys(manifest, spec, seen, report)
+        InstallLayout.content_kinds.each do |kind|
+          (manifest.section_keys(kind.type) - seen[kind.type]).each do |key|
+            report.warn "#{spec.name}: manifest #{kind.section} entry '#{key}' names no shipped #{kind.shipped_label}"
+          end
         end
       end
 
-      def skill_paths(spec, warnings: [])
-        roots = [
-          File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive", "skills"),
-          File.join(spec.full_gem_path, "skills")
-        ]
-        if (override = skills_dir_override(spec))
-          roots << File.join(spec.full_gem_path, override)
-        end
+      def skill_paths(spec, manifest:, report: Report.new)
+        roots = artifact_roots(spec, InstallLayout.kind(:skill), manifest)
 
         candidates = []
         seen = {}
@@ -107,17 +155,24 @@ module Rails
             candidates << {
               dir: dir,
               rel: dir.delete_prefix(root).delete_prefix("/"),
-              path: resolve_same_dir_tie(dir, group, warnings)
+              path: resolve_same_dir_tie(dir, group, report)
             }
           end
         end
 
-        pair_with_templates(candidates, spec, warnings: warnings)
+        pair_with_templates(candidates, spec, manifest: manifest, report: report)
+      end
+
+      def templates_root(spec, manifest)
+        File.join(
+          spec.full_gem_path,
+          manifest.skill_templates_dir || File.join("lib", spec.name, "hyperdrive", "skills")
+        )
       end
 
-      def resolve_same_dir_tie(dir, group, warnings)
+      def resolve_same_dir_tie(dir, group, report)
         return group.first unless group.size > 1
-        warnings << "skip #{File.join(dir, "SKILL.md.erb")}: SKILL.md in the same directory takes precedence"
+        report.skip "skip #{File.join(dir, "SKILL.md.erb")}: SKILL.md in the same directory takes precedence"
         group.find { |p| File.basename(p) == "SKILL.md" }
       end
 
@@ -126,17 +181,17 @@ module Rails
       # the definition, the static dir the support root. The static SKILL.md is
       # never parsed — falling back to it when the template fails to render
       # would silently un-condition the skill.
-      def pair_with_templates(candidates, spec, warnings:)
-        templates_root = File.join(spec.full_gem_path, skill_templates_dir(spec))
+      def pair_with_templates(candidates, spec, manifest:, report:)
+        root = templates_root(spec, manifest)
 
         pairs = {}
         candidates.each do |cand|
           next unless File.basename(cand[:path]) == "SKILL.md"
-          template_dir = File.expand_path(File.join(templates_root, cand[:rel]))
+          template_dir = File.expand_path(File.join(root, cand[:rel]))
           next if template_dir == File.expand_path(cand[:dir])
           template = File.join(template_dir, "SKILL.md.erb")
           next unless File.file?(template)
-          warn_template_extras(template_dir, warnings)
+          warn_template_extras(template_dir, report)
           pairs[cand[:dir]] = { template: template, template_dir: template_dir }
         end
 
@@ -152,18 +207,77 @@ module Rails
         end
       end
 
-      # The content dir is the single source of truth for supporting files.
-      def warn_template_extras(template_dir, warnings)
+      # The template dir holds only templates; static content is the paired
+      # content dir's to ship.
+      def warn_template_extras(template_dir, report)
         extras = Dir.glob(File.join(template_dir, "**", "*"))
-                    .select { |f| File.file?(f) && f != File.join(template_dir, "SKILL.md.erb") }
+                    .select { |f| File.file?(f) && !erb_template?(f) }
         return if extras.empty?
-        warnings << "#{template_dir}: ignoring #{extras.size} file(s) besides SKILL.md.erb; " \
-                    "supporting files ship in the paired content directory"
+        report.warn "#{template_dir}: ignoring #{extras.size} file(s) besides SKILL.md.erb and " \
+          "supporting *.md.erb templates; static supporting files ship in the paired content directory"
       end
 
-      def guideline_paths(spec)
-        root = File.join(spec.full_gem_path, "lib", spec.name, "hyperdrive", "guidelines")
-        Dir.glob(File.join(root, "*.md"))
+      # 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, 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)
+        roots = kind.roots_for(spec.name.to_s).map { |rel| File.join(spec.full_gem_path, rel) }
+        override = kind.dir_key && manifest.dir(kind.dir_key)
+        roots << File.join(spec.full_gem_path, override) if override
+        roots
       end
 
       # Many gemspecs package files via `git ls-files`, so a contributor-facing
@@ -171,14 +285,12 @@ module Rails
       # intent. Only an explicit signal makes a gem's content installable.
       def opted_in?(spec, enabled_gems:)
         return true if enabled_gems.include?(spec.name.to_s)
-        return true if metadata_present?(spec, "rails_hyperdrive_skills_dir")
-        return true if metadata_present?(spec, "rails_hyperdrive_skill_templates_dir")
-        return true if metadata_present?(spec, "rails_hyperdrive_targets")
+        return true if metadata_present?(spec, "hyperdrive_targets")
         return true if GemManifest.opt_in?(spec)
 
         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)
@@ -190,75 +302,77 @@ module Rails
       # Report-only, glob-only (no file reads): SKILL.md presence is the
       # signal, and SKILL.md.erb is excluded — raw ERB is not skills.sh
       # content. Parse problems surface as warnings once the gem is enabled.
-      def notice_skills_sh_content(spec, notices:)
+      def notice_skills_sh_content(spec, report:)
         found = Dir.glob(File.join(spec.full_gem_path, "skills", "**", "SKILL.md"))
         return if found.empty?
 
         count = found.map { |p| File.dirname(p) }.uniq.size
-        notices << "gem '#{spec.name}' ships #{count} skills.sh skill(s); add \"#{spec.name}\" to enabled: " \
-                   "in .hyperdrive/lock.yml and re-run bin/rails hyperdrive:sync to install them"
-      end
-
-      # ".." segments are rejected to prevent escaping the gem root.
-      def skills_dir_override(spec)
-        return nil unless spec.respond_to?(:metadata)
-        raw = spec.metadata && spec.metadata["rails_hyperdrive_skills_dir"]
-        return nil if raw.nil? || raw.to_s.strip.empty?
-        return nil if raw.to_s.split(%r{[/\\]}).include?("..")
-        raw.to_s
-      end
-
-      def skill_templates_dir(spec)
-        default = File.join("lib", spec.name, "hyperdrive", "skills")
-        return default unless spec.respond_to?(:metadata)
-        raw = spec.metadata && spec.metadata["rails_hyperdrive_skill_templates_dir"]
-        return default if raw.nil? || raw.to_s.strip.empty?
-        return default if raw.to_s.split(%r{[/\\]}).include?("..")
-        raw.to_s
+        report.notices << "gem '#{spec.name}' ships #{count} skills.sh skill(s); add \"#{spec.name}\" to enabled: " \
+                          "in .hyperdrive/lock.yml and re-run bin/rails hyperdrive:sync to install them"
       end
 
       # Frontmatter's schema is exactly name and description; any other key is
       # unknown to the parser and rides untouched in the installed body.
-      def parse(path, source_spec:, type:, resolved:, warnings:, gate:, support_root: nil)
+      # Returns the Artifact, :gate_miss when a well-formed gate simply does
+      # not match the bundle, or nil for a hard skip.
+      def parse(path, source_spec:, kind:, resolved:, report:, gate:, key:, manifest:, support_root: nil)
         support_root ||= File.dirname(path)
         body = File.read(path)
         if erb_template?(path)
           begin
             body = SkillTemplate.render(body, resolved: resolved)
           rescue SyntaxError, StandardError => e
-            warnings << "skip #{path}: ERB render failed (#{e.message})"
+            # A template reaching for a helper this installer lacks raises
+            # here, and the fence is the only thing the user can act on.
+            if (required = unmet_fence(gate))
+              report.fence fence_message(kind.type, key, source_spec, required)
+            else
+              report.skip "skip #{path}: ERB render failed (#{e.message})"
+            end
             return nil
           end
         end
-        frontmatter, _rest = split_frontmatter(body)
-        unless frontmatter
-          warnings << "skip #{path}: missing or malformed frontmatter"
-          return nil
+
+        meta = {}
+        if kind.frontmatter == :required
+          frontmatter, _rest = split_frontmatter(body)
+          unless frontmatter
+            report.skip "skip #{path}: missing or malformed frontmatter"
+            return nil
+          end
+
+          # Date is permitted because unknown frontmatter keys are user content;
+          # a bare date value must not fail the parse.
+          meta = YAML.safe_load(frontmatter, permitted_classes: [Symbol, Date]) || {}
+          unless meta["name"] && meta["description"]
+            report.skip "skip #{path}: missing a required field (name, description)"
+            return nil
+          end
         end
 
-        # Date is permitted because unknown frontmatter keys are user content;
-        # a bare date value must not fail the parse.
-        meta        = YAML.safe_load(frontmatter, permitted_classes: [Symbol, Date]) || {}
-        name        = meta["name"]
+        name        = kind.identity == :frontmatter ? meta["name"] : prefixed_stem(path, kind, manifest)
         description = meta["description"]
 
-        unless name && description
-          warnings << "skip #{path}: missing a required field (name, description)"
+        # The fence is decided before the bundle gate so a fenced-out artifact
+        # reports the one thing the user can act on.
+        if (required = unmet_fence(gate))
+          report.fence fence_message(kind.type, name, source_spec, required)
           return nil
         end
 
-        matched = match_targets(gate.targets, gate.versions, resolved)
+        matched = match_targets(gate.targets, gate.versions, resolved, mode: gate.match_mode)
         if matched.empty?
-          warnings << "skip #{name} (from #{source_spec.name}): #{no_match_reason(gate.targets, gate.versions, resolved)}"
-          return nil
+          reason = no_match_reason(gate.targets, gate.versions, resolved, mode: gate.match_mode)
+          report.skip "skip #{name} (from #{source_spec.name}): #{reason}"
+          return :gate_miss
         end
 
         Artifact.new(
           name: name.to_s,
-          description: description.to_s,
+          description: description&.to_s,
           target_gem: matched,
           versions: gate.versions,
-          artifact_type: type,
+          artifact_type: kind.type,
           source_gem: source_spec.name.to_s,
           path: path,
           body: body,
@@ -266,10 +380,10 @@ module Rails
           source_root: source_spec.full_gem_path.to_s,
           support_root: support_root,
           support_files:
-            if type == :skill
-              conditioned_support_files(
-                support_root, gate.conditional,
-                resolved: resolved, warnings: warnings,
+            if kind.dir_shaped?
+              skill_support_files(
+                path, support_root, gate.conditional,
+                source_spec: source_spec, manifest: manifest, resolved: resolved, report: report,
                 label: "#{name} (from #{source_spec.name})"
               )
             else
@@ -277,104 +391,210 @@ module Rails
             end
         )
       rescue Psych::Exception
-        warnings << "skip #{path}: malformed YAML frontmatter"
+        report.skip "skip #{path}: malformed YAML frontmatter"
         nil
       end
 
-      # Everything in a skill's directory besides SKILL.md(.erb) ships as raw
-      # bytes, with no frontmatter contract. ".." segments are rejected to keep
-      # the tree inside the skill directory.
-      def support_files_for(skill_dir)
-        Dir.glob(File.join(skill_dir, "**", "*")).filter_map do |file|
+      # A kind identified by its filename may carry a gem-wide name prefix from
+      # the manifest; the manifest still keys its own entries by the shipped
+      # filename.
+      def prefixed_stem(path, kind, manifest)
+        stem = File.basename(target_path(path), ".md")
+        prefix = manifest.name_prefix(kind.type)
+        prefix ? "#{prefix}-#{stem}" : stem
+      end
+
+      def fence_message(type, label, source_spec, required)
+        "#{type} '#{label}' (from #{source_spec.name}) requires rails-hyperdrive #{required} " \
+          "(this is #{Rails::Hyperdrive::VERSION}); upgrade rails-hyperdrive to install it"
+      end
+
+      # Dir-relative paths of everything under `root` besides SKILL.md(.erb).
+      # ".." segments are rejected to keep the tree inside that directory.
+      def support_relpaths(root, glob: "**/*")
+        return [] if root.nil?
+
+        Dir.glob(File.join(root, glob)).filter_map do |file|
           next unless File.file?(file)
-          rel = file.delete_prefix("#{skill_dir}/")
+          rel = file.delete_prefix("#{root}/")
           next if SKILL_FILE_NAMES.include?(File.basename(rel))
           next if rel.split(%r{[/\\]}).include?("..")
-          { path: rel, body: File.binread(file) }
+          rel
         end
       end
 
-      def conditioned_support_files(skill_dir, conditional, resolved:, warnings:, label:)
-        files = support_files_for(skill_dir)
-        files = apply_conditional_filter(files, conditional, resolved: resolved, warnings: warnings, label: label)
-        render_support_templates(files, skill_dir, resolved: resolved, warnings: warnings)
+      # nil when the definition file sits in the support root, i.e. the skill
+      # is not template-paired.
+      def template_dir_for(path, support_root)
+        dir = File.dirname(path)
+        dir unless File.expand_path(dir) == File.expand_path(support_root)
+      end
+
+      # Supporting files ship as raw bytes, with no frontmatter contract.
+      def support_files_for(skill_dir)
+        support_relpaths(skill_dir).map do |rel|
+          { path: rel, body: File.binread(File.join(skill_dir, rel)), root: skill_dir }
+        end
+      end
+
+      def template_support_files(template_dir)
+        support_relpaths(template_dir, glob: "**/*.md.erb").map do |rel|
+          { path: rel, body: File.binread(File.join(template_dir, rel)), root: template_dir, template: true }
+        end
+      end
+
+      def skill_support_files(path, support_root, conditional, source_spec:, manifest:, resolved:, report:, label:)
+        conditioned_support_files(
+          support_root, conditional,
+          resolved: resolved, report: report, label: label,
+          template_dir: template_dir_for(path, support_root), source_root: source_spec.full_gem_path,
+          public_root: public_support_root?(source_spec, manifest, support_root)
+        )
+      end
+
+      def conditioned_support_files(skill_dir, conditional, resolved:, report:, label:,
+                                    template_dir:, source_root:, public_root:)
+        content = support_files_for(skill_dir)
+        templates = template_support_files(template_dir)
+        warn_public_support_templates(content, skill_dir, report) if public_root
+
+        # A template-side file owns its target path whatever its own outcome:
+        # installing the content-side face when the template is gated out or
+        # fails to render would silently un-condition the file.
+        claimed = templates.map { |f| target_path(f[:path]) }
+        files = apply_conditional_filter(content + templates, conditional,
+          resolved: resolved, report: report, label: label)
+        files = files.reject { |f| !f[:template] && claimed.include?(target_path(f[:path])) }
+
+        render_support_templates(files, resolved: resolved, report: report, source_root: source_root)
+      end
+
+      # Everything under a public skills root is copied verbatim by generic
+      # skills.sh consumers, so a template there hands them raw ERB.
+      def warn_public_support_templates(files, skill_dir, report)
+        return if files.none? { |f| erb_template?(f[:path]) }
+        report.warn "#{skill_dir}: supporting *.md.erb template(s) sit under a public skills root; " \
+          "move them to the paired template directory and commit their rendered faces here"
+      end
+
+      def public_support_root?(spec, manifest, support_root)
+        dir = "#{File.expand_path(support_root)}/"
+        return false if dir.start_with?("#{File.expand_path(templates_root(spec, manifest))}/")
+
+        roots = [File.join(spec.full_gem_path, "skills")]
+        roots << File.join(spec.full_gem_path, manifest.skills_dir) if manifest.skills_dir
+        roots.any? { |root| dir.start_with?("#{File.expand_path(root)}/") }
       end
 
       # Fail-open: a malformed condition warns and installs its file
       # unconditionally — a surplus supporting file is harmless, while a
       # missing one breaks links from SKILL.md.
-      def apply_conditional_filter(files, conditional, resolved:, warnings:, label:)
+      def apply_conditional_filter(files, conditional, resolved:, report:, label:)
         return files if conditional.nil?
         unless conditional.is_a?(Hash)
-          warnings << "#{label}: conditional: must be a map of supporting-file path to {gem:, versions:}; installing all supporting files"
+          report.warn "#{label}: conditional: must be a map of supporting-file path to a gating map; installing all supporting files"
           return files
         end
 
         conditions = conditional.transform_keys(&:to_s)
-        shipped = files.map { |f| f[:path] }
+        shipped = files.flat_map { |f| [f[:path], target_path(f[:path])] }
         conditions.each_key do |key|
           if SKILL_FILE_NAMES.include?(key)
-            warnings << "#{label}: conditional key '#{key}' ignored; the entry's own gem:/versions: gate the whole skill"
+            report.warn "#{label}: conditional key '#{key}' ignored; the entry's own gem: gates the whole skill"
           elsif !shipped.include?(key)
-            warnings << "#{label}: conditional key '#{key}' names no shipped supporting file"
+            report.warn "#{label}: conditional key '#{key}' names no shipped supporting file"
           end
         end
 
         files.select do |file|
-          next true unless conditions.key?(file[:path])
-          conditional_satisfied?(file[:path], conditions[file[:path]], resolved, warnings: warnings, label: label)
+          key = condition_key_for(file[:path], conditions, report: report, label: label)
+          next true unless key
+          conditional_satisfied?(key, conditions[key], resolved, report: report, label: label)
         end
       end
 
-      def conditional_satisfied?(key, entry, resolved, warnings:, label:)
-        unless entry.is_a?(Hash)
-          warnings << "#{label}: conditional entry for '#{key}' must be a map with gem: (and optional versions:); installing the file"
-          return true
+      # A template-backed file may be keyed by its shipped *.md.erb name or by
+      # the rendered face it installs as; the exact spelling wins when a
+      # manifest carries both.
+      def condition_key_for(path, conditions, report:, label:)
+        face = target_path(path)
+        return conditions.key?(path) ? path : nil if face == path
+
+        if conditions.key?(path)
+          if conditions.key?(face)
+            report.warn "#{label}: conditional keys '#{path}' and '#{face}' both gate '#{face}'; using '#{path}'"
+          end
+          return path
         end
+        face if conditions.key?(face)
+      end
 
-        targets = entry["gem"] && GemManifest.parse_targets(entry["gem"])
-        if targets.nil? || targets.empty?
-          warnings << "#{label}: conditional entry for '#{key}' needs gem: naming a gem, a comma-separated list, or a YAML list; installing the file"
+      def conditional_satisfied?(key, entry, resolved, report:, label:)
+        unless entry.is_a?(Hash)
+          report.warn "#{label}: conditional entry for '#{key}' must be a map with gem:; installing the file"
           return true
         end
 
-        versions = entry["versions"]
-        if GemManifest.malformed_requirements?(versions)
-          warnings << "#{label}: conditional entry for '#{key}' has an unparsable versions: requirement; installing the file"
+        entry = entry.transform_keys(&:to_s)
+        gem_key = GemManifest.gem_key(entry)
+        report.warn "#{label}: conditional entry for '#{key}': #{gem_key.warning}" if gem_key.warning
+
+        parsed = gem_key.present ? GemManifest.parse_targets(gem_key.value) : nil
+        if parsed.nil? || parsed.targets.empty?
+          report.warn "#{label}: conditional entry for '#{key}' needs gem: naming #{GemManifest::GEM_FORMS}; installing the file"
           return true
         end
+        report.warn "#{label}: conditional entry for '#{key}': #{GemManifest::VERSIONS_REMOVED}" if entry.key?("versions")
+        report.warn "#{label}: conditional entry for '#{key}' gem: #{parsed.warning}" if parsed.warning
 
-        match_targets(targets, versions, resolved).any?
+        match_targets(parsed.targets, parsed.versions, resolved, mode: parsed.match_mode).any?
       end
 
-      def render_support_templates(files, skill_dir, resolved:, warnings:)
+      def render_support_templates(files, resolved:, report:, source_root: nil)
         plain_paths = files.map { |f| f[:path] }
         files.filter_map do |file|
-          next file unless erb_template?(file[:path])
+          next { path: file[:path], body: file[:body] } unless erb_template?(file[:path])
 
-          target = file[:path].delete_suffix(".erb")
+          target = target_path(file[:path])
           if plain_paths.include?(target)
-            warnings << "skip #{File.join(skill_dir, file[:path])}: #{target} in the same directory takes precedence"
+            report.skip "skip #{File.join(file[:root], file[:path])}: #{target} in the same directory takes precedence"
             next nil
           end
 
           begin
-            { path: target, body: SkillTemplate.render(file[:body], resolved: resolved) }
+            rendered = { path: target, body: SkillTemplate.render(file[:body], resolved: resolved) }
           rescue SyntaxError, StandardError => e
-            warnings << "skip #{File.join(skill_dir, file[:path])}: ERB render failed (#{e.message})"
-            nil
+            report.skip "skip #{File.join(file[:root], file[:path])}: ERB render failed (#{e.message})"
+            next nil
           end
+          file[:template] ? rendered.merge(source_relpath: template_relpath(file, source_root)) : rendered
         end
       end
 
+      # The relpath a later merge reconstructs the ancestor from: template-side,
+      # and .erb-stripped so AncestorLocator's twin fallback resolves it.
+      def template_relpath(file, source_root)
+        return nil if source_root.nil? || source_root.to_s.empty?
+
+        prefix = "#{File.expand_path(source_root.to_s)}/"
+        dir = File.expand_path(file[:root].to_s)
+        return nil unless dir.start_with?(prefix)
+        target_path(File.join(dir.delete_prefix(prefix), file[:path]))
+      end
+
       def erb_template?(path)
         path.end_with?(".md.erb")
       end
 
+      def target_path(path)
+        erb_template?(path) ? path.delete_suffix(".erb") : path
+      end
+
       # Guideline frontmatter is stripped because the installed file is
       # @-included eagerly into agent context, where it would be inert noise.
       def install_ready_body(artifact)
-        return artifact.body if artifact.skill?
+        kind = InstallLayout.kind(artifact.artifact_type)
+        return artifact.body unless kind&.install_body == :strip_frontmatter
 
         _frontmatter, rest = split_frontmatter(artifact.body)
         (rest || artifact.body).sub(/\A\n+/, "")
@@ -391,47 +611,89 @@ module Rails
         [lines[1...absolute_closing].join, lines[(absolute_closing + 1)..].join]
       end
 
-      def match_targets(targets, versions, resolved)
+      # Compares against the running installer's own version rather than the
+      # bundle, so content depending on an installer feature stays out of apps
+      # whose rails-hyperdrive cannot honor it. Returns the unmet requirement
+      # for the warning, or nil when the fence is absent or satisfied.
+      def unmet_fence(gate)
+        return nil if gate.hyperdrive_version.nil?
+
+        parts = GemManifest.requirement_parts(gate.hyperdrive_version)
+        return nil if Gem::Requirement.new(*parts).satisfied_by?(Gem::Version.new(Rails::Hyperdrive::VERSION))
+        parts.join(", ")
+      end
+
+      def match_targets(targets, versions, resolved, mode: :any)
         return ["*"] if targets.include?("*")
 
-        targets.select do |t|
+        matched = targets.select do |t|
           version = resolved[t]
           version && version_satisfied?(versions, t, version)
         end
+        return matched unless mode == :all
+        matched.size == targets.size ? matched : []
       end
 
       def version_satisfied?(versions, target, version)
-        requirement = versions.is_a?(Hash) ? versions[target] : versions
+        requirement = requirement_for(versions, target)
         requirement.nil? || SkillTemplate.version_matches?(requirement, version)
       end
 
-      def no_match_reason(targets, versions, resolved)
+      def requirement_for(versions, target)
+        versions.is_a?(Hash) ? versions[target] : versions
+      end
+
+      def no_match_reason(targets, versions, resolved, mode: :any)
+        return all_no_match_reason(targets, versions, resolved) if mode == :all
+
         present = targets.select { |t| resolved.key?(t) }
         if present.empty?
           label = targets.size == 1 ? "target gem" : "target gems"
           "#{label} '#{targets.join(", ")}' not in bundle"
         else
-          present.map { |t| "#{t} #{resolved[t]} does not satisfy '#{versions.is_a?(Hash) ? versions[t] : versions}'" }
-                 .join("; ")
+          present.map { |t| unsatisfied_reason(t, versions, resolved) }.join("; ")
         end
       end
 
+      def all_no_match_reason(targets, versions, resolved)
+        present, missing = targets.partition { |t| resolved.key?(t) }
+        reasons = []
+        unless missing.empty?
+          label = missing.size == 1 ? "required target gem" : "required target gems"
+          reasons << "#{label} '#{missing.join(", ")}' not in bundle"
+        end
+        present.each do |t|
+          next if version_satisfied?(versions, t, resolved[t])
+          reasons << unsatisfied_reason(t, versions, resolved)
+        end
+        reasons.join("; ")
+      end
+
+      def unsatisfied_reason(target, versions, resolved)
+        "#{target} #{resolved[target]} does not satisfy '#{requirement_for(versions, target)}'"
+      end
+
       def safe_bundler_specs
         ::Bundler.load.specs.to_a
       rescue ::Bundler::BundlerError
         []
       end
 
-      private_class_method :each_artifact_path, :warn_unknown_manifest_keys, :skill_paths,
-                           :guideline_paths,
+      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,
-                           :skills_dir_override, :skill_templates_dir, :parse, :support_files_for,
-                           :conditioned_support_files, :apply_conditional_filter,
-                           :conditional_satisfied?,
-                           :render_support_templates, :erb_template?,
-                           :match_targets,
-                           :version_satisfied?, :no_match_reason, :safe_bundler_specs
+                           :parse, :fence_message,
+                           :erb_template?, :support_files_for,
+                           :template_support_files, :skill_support_files,
+                           :conditioned_support_files, :warn_public_support_templates,
+                           :public_support_root?, :apply_conditional_filter,
+                           :condition_key_for, :conditional_satisfied?,
+                           :render_support_templates, :template_relpath,
+                           :unmet_fence, :match_targets,
+                           :version_satisfied?, :requirement_for, :no_match_reason,
+                           :all_no_match_reason, :unsatisfied_reason, :safe_bundler_specs
     end
   end
 end