rails-hyperdrive 0.6.0 → 0.7.0

data/lib/rails/hyperdrive/lock_file.rb

@@ -4,11 +4,11 @@ module Rails
   module Hyperdrive
     # installed_at is volatile metadata, never an input to any comparison.
     class LockFile
-      SCHEMA_VERSION = 1
+      SCHEMA_VERSION = 2
       STATE_PRESENT  = "present".freeze
       STATE_REMOVED  = "removed-by-user".freeze
 
-      DISABLED_KEYS = { skill: "skills", guideline: "guidelines" }.freeze
+      DISABLED_KEYS = { skill: "skills", guideline: "guidelines", agent: "agents", command: "commands" }.freeze
 
       # In-memory form of one files: entry. On disk, source_gem and
       # source_version are a single "gem@version" string; the split/join lives
@@ -19,7 +19,7 @@ module Rails
         end
       end
 
-      attr_reader :path
+      attr_reader :path, :schema_version
       attr_accessor :claude_md_state
 
       # Load existing lock state from disk (absent file → empty lock).
@@ -27,6 +27,13 @@ module Rails
         new(path).tap(&:read)
       end
 
+      # Every surface reporting an orphan must name the same two cases, or a
+      # sync and a bundle install would disagree about why a file is stranded.
+      def self.orphan_reason(source_label:, source_gem:, bundled:)
+        return "no longer shipped by #{source_label}" unless bundled
+        "#{source_gem} is still bundled but did not offer this file"
+      end
+
       def initialize(path)
         @path = path.to_s
         @claude_md_state = nil # nil = no lock has been written yet
@@ -34,6 +41,7 @@ module Rails
         @document = {}         # raw parsed YAML, kept so unknown keys survive
         @disabled = empty_disabled
         @enabled = []
+        @schema_version = nil
       end
 
       def read
@@ -43,6 +51,7 @@ module Rails
         return self unless data.is_a?(Hash)
 
         @document = data
+        @schema_version = data["version"]
         claude_md = data["claude_md"]
         @claude_md_state = claude_md["state"] if claude_md.is_a?(Hash)
         @disabled = parse_disabled(data["disabled"])
@@ -57,6 +66,19 @@ module Rails
         self
       end
 
+      # A lock written by a newer installer holds state this one cannot read,
+      # so rewriting it would silently drop the user's settings. A missing or
+      # non-numeric version reads as not ahead: every lock ever written carries
+      # an integer version, and a hand-broken one must not block a sync.
+      def schema_ahead?
+        @schema_version.is_a?(Numeric) && @schema_version > SCHEMA_VERSION
+      end
+
+      def schema_ahead_message(display_path)
+        "#{display_path} was written by a newer rails-hyperdrive (lock schema #{@schema_version}, " \
+          "this installer supports #{SCHEMA_VERSION}); upgrade rails-hyperdrive"
+      end
+
       def entry(file_path)
         @files[file_path.to_s]
       end

data/lib/rails/hyperdrive/manifest_lint.rb

@@ -0,0 +1,230 @@
+require "yaml"
+require "rails/hyperdrive/bundler_artifact_discovery"
+require "rails/hyperdrive/gem_manifest"
+require "rails/hyperdrive/gemspec_locator"
+require "rails/hyperdrive/install_layout"
+
+module Rails
+  module Hyperdrive
+    # Author-side check of a companion gem's hyperdrive.yml, run in the
+    # companion's own repo. Where the installer warns and falls open — so that
+    # a manifest written for a newer schema never blocks an install — this
+    # fails, and unknown keys fail outright: the author's own rails-hyperdrive
+    # is the one that knows the whole schema. A manifest that passes draws no
+    # gating warning at install time.
+    module ManifestLint
+      Error = GemspecLocator::Error
+
+      GATE_KEYS = %w[gem gems hyperdrive_version].freeze
+      DIR_KEYS = GemManifest::DIR_KEYS
+      ROOT_KEYS = (GATE_KEYS + DIR_KEYS + InstallLayout.content_kinds.map(&:section)).freeze
+      SKILL_ENTRY_KEYS = (GATE_KEYS + %w[conditional]).freeze
+      CONDITIONAL_ENTRY_KEYS = %w[gem gems].freeze
+      RETIRED_VERSION_KEYS = %w[versions version].freeze
+      RETIRED_VERSION_HINT = "is not a gating key; put the requirement on the gem: member, " \
+                             "e.g. `- name: \">= 1.0\"`".freeze
+
+      # `manifest` is nil when the gem ships none, which is legal.
+      Result = Struct.new(:manifest, :problems, keyword_init: true)
+
+      # Discovery resolves every root against an installed gem's path; in the
+      # companion's repo that is the checkout.
+      RepoSpec = Struct.new(:name, :full_gem_path, :metadata, keyword_init: true)
+
+      module_function
+
+      def check(gemspec: nil, dir: Dir.pwd)
+        spec, gem_root = GemspecLocator.load_spec(gemspec, dir)
+        relpath = GemManifest.manifest_relpath(spec)
+        path = File.join(gem_root, relpath)
+        return missing_manifest(spec, relpath) unless File.file?(path)
+
+        repo_spec = RepoSpec.new(name: spec.name, full_gem_path: gem_root, metadata: spec.metadata || {})
+        Result.new(manifest: relpath, problems: problems_in(path, repo_spec))
+      end
+
+      # Shipping no manifest is legal, but a declared path that is not a file
+      # leaves the gem opted in as a companion with every artifact ungated —
+      # the author-side slip this lint exists to catch.
+      def missing_manifest(spec, relpath)
+        declared = (spec.metadata || {})[GemManifest::METADATA_KEY].to_s
+        return Result.new(manifest: nil, problems: []) unless declared == relpath
+
+        Result.new(
+          manifest: relpath,
+          problems: ["gemspec metadata #{GemManifest::METADATA_KEY} names '#{relpath}', which is not a file"]
+        )
+      end
+
+      def problems_in(path, repo_spec)
+        problems = []
+        root = parse_root(path, problems)
+        return problems if root.nil?
+
+        check_keys(root, ROOT_KEYS, "top level", problems)
+        check_gate(root, "top level", problems)
+        check_dirs(root, problems)
+
+        manifest = GemManifest.load(repo_spec, warnings: [])
+        skills = shipped_skills(repo_spec, manifest)
+        InstallLayout.content_kinds.each do |kind|
+          shipped = kind.dir_shaped? ? skills.keys : shipped_flat(repo_spec, kind, manifest)
+          each_entry(root, kind, shipped, problems) do |key, entry|
+            where = "#{kind.section} entry '#{key}'"
+            check_keys(entry, kind.dir_shaped? ? SKILL_ENTRY_KEYS : GATE_KEYS, where, problems)
+            check_gate(entry, where, problems)
+            next unless kind.dir_shaped? && entry.key?("conditional")
+            check_conditional(entry["conditional"], where, skills[key], problems)
+          end
+        end
+
+        problems
+      end
+
+      # nil means nothing further is readable; an empty manifest is legal.
+      def parse_root(path, problems)
+        root, failure = GemManifest.read_root(path)
+        problems << failure unless root
+        root
+      end
+
+      def each_entry(root, kind, shipped, problems)
+        value = root[kind.section]
+        return if value.nil?
+        unless value.is_a?(Hash)
+          problems << "#{kind.section}: must be a map of #{kind.shipped_label} keys to gating maps"
+          return
+        end
+
+        entries = value.transform_keys(&:to_s)
+        check_section_settings(entries, kind, problems)
+
+        entries.each do |key, entry|
+          next if Array(kind.prefix_key).include?(key)
+
+          unless shipped.include?(key)
+            problems << "#{kind.section} entry '#{key}' names no shipped #{kind.shipped_label}"
+          end
+          unless entry.is_a?(Hash)
+            problems << "#{kind.section} entry '#{key}' must be a map of gating keys"
+            next
+          end
+          yield key, entry.transform_keys(&:to_s)
+        end
+      end
+
+      # A kind's section-level scalar is a setting, not a gating entry.
+      def check_section_settings(entries, kind, problems)
+        Array(kind.prefix_key).each do |key|
+          next unless entries.key?(key)
+
+          value = entries[key]
+          next if value.is_a?(String) && !value.strip.empty? &&
+                  !value.match?(%r{[/\\]}) && !value.include?("..")
+          problems << "#{kind.section}: #{key}: must be a name prefix with no path separators or '..' segments"
+        end
+      end
+
+      def check_keys(map, allowed, where, problems)
+        (map.keys - allowed).each do |key|
+          problems << if RETIRED_VERSION_KEYS.include?(key)
+            "#{where}: '#{key}:' #{RETIRED_VERSION_HINT}"
+          else
+            "#{where}: unknown key '#{key}'#{did_you_mean(key, allowed)}; " \
+              "allowed keys are #{allowed.join(", ")}"
+          end
+        end
+      end
+
+      def check_dirs(root, problems)
+        DIR_KEYS.each do |key|
+          next unless root.key?(key)
+
+          dir, failure = GemManifest.read_dir(root, key)
+          next if dir
+          problems << "top level: #{failure || "#{key}: must name a directory relative to the gem root"}"
+        end
+      end
+
+      def did_you_mean(key, allowed)
+        near = allowed.find { |a| a.start_with?(key) || key.start_with?(a) }
+        near ? " (did you mean '#{near}'?)" : ""
+      end
+
+      # The parse rules come from GemManifest itself, so a form it accepts is
+      # never reported here and a form it falls open on always is. A parser
+      # warning counts as a failure: it names a spelling that installs, but not
+      # as written.
+      def check_gate(map, where, problems, fence: true)
+        gem_key = GemManifest.gem_key(map)
+        problems << "#{where}: gem: and gems: are aliases; keep only one" if gem_key.conflict
+
+        if gem_key.present
+          parsed = GemManifest.parse_targets(gem_key.value)
+          if parsed.nil? || parsed.targets.empty?
+            problems << "#{where}: gem: must name #{GemManifest::GEM_FORMS}"
+          elsif parsed.warning
+            problems << "#{where}: gem: #{parsed.warning}"
+          end
+        end
+
+        return unless fence && map.key?("hyperdrive_version")
+        return unless GemManifest.malformed_fence?(map["hyperdrive_version"])
+        problems << "#{where}: hyperdrive_version: must be a version requirement, e.g. \">= 0.8\""
+      end
+
+      # `shipped` is nil when the owning skills entry names no shipped
+      # directory, which is already reported — every key would repeat it.
+      def check_conditional(value, where, shipped, problems)
+        unless value.is_a?(Hash)
+          problems << "#{where}: conditional: must be a map of supporting-file path to a gating map"
+          return
+        end
+
+        keys = value.keys.map(&:to_s)
+        value.each do |key, entry|
+          key = key.to_s
+          inner = "#{where} conditional key '#{key}'"
+          face = BundlerArtifactDiscovery.target_path(key)
+          if BundlerArtifactDiscovery::SKILL_FILE_NAMES.include?(key)
+            problems << "#{inner}: the entry's own gem: gates the whole skill"
+          elsif shipped && !shipped.include?(key)
+            problems << "#{inner}: names no shipped supporting file"
+          end
+          problems << "#{inner}: '#{face}' keys the same file; keep one spelling" if face != key && keys.include?(face)
+
+          unless entry.is_a?(Hash)
+            problems << "#{inner}: must be a map with gem:"
+            next
+          end
+          entry = entry.transform_keys(&:to_s)
+          check_keys(entry, CONDITIONAL_ENTRY_KEYS, inner, problems)
+          check_gate(entry, inner, problems, fence: false)
+          problems << "#{inner}: gem: is required" unless GemManifest.gem_key(entry).present
+        end
+      end
+
+      # Maps each skill's manifest key to the dir-relative paths a conditional:
+      # entry may name: every supporting file as shipped, plus the rendered
+      # face of each *.md.erb, since either spelling gates the same file.
+      def shipped_skills(repo_spec, manifest)
+        found = BundlerArtifactDiscovery.skill_paths(repo_spec, manifest: manifest)
+        found.each_with_object({}) do |(path, support_root, rel), h|
+          shipped = BundlerArtifactDiscovery.support_relpaths(support_root) |
+                    BundlerArtifactDiscovery.support_relpaths(
+                      BundlerArtifactDiscovery.template_dir_for(path, support_root), glob: "**/*.md.erb"
+                    )
+          h[rel] = h.fetch(rel, []) | shipped | shipped.map { |p| BundlerArtifactDiscovery.target_path(p) }
+        end
+      end
+
+      def shipped_flat(repo_spec, kind, manifest)
+        BundlerArtifactDiscovery.flat_paths(repo_spec, kind, manifest: manifest).map { |p| File.basename(p) }
+      end
+
+      private_class_method :missing_manifest, :problems_in, :parse_root, :each_entry, :check_section_settings,
+                           :check_keys, :check_dirs, :did_you_mean, :check_gate, :check_conditional,
+                           :shipped_skills, :shipped_flat
+    end
+  end
+end

data/lib/rails/hyperdrive/skill_template.rb

@@ -3,8 +3,9 @@ require "erb"
 module Rails
   module Hyperdrive
     # Renders a skill's *.md.erb sources against the app's resolved bundle.
-    # The template binding is sealed: exactly three helpers over the resolved
-    # {gem name => Gem::Version} map, no app context, no arbitrary lookup.
+    # The three 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
       class Context
         def initialize(resolved)
@@ -31,9 +32,10 @@ module Rails
         end
       end
 
-      # Fail-open binding for the canonical render: every gem reads as present
-      # at any requested version, so the output includes every conditional
-      # branch. There is no bundle to resolve against, so gem_version is nil.
+      # 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.
       class CanonicalContext
         def gem?(_name, _requirement = nil)
           true

data/lib/rails/hyperdrive/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-hyperdrive
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Bakaface
@@ -69,8 +69,8 @@ description: |
   Rails Hyperdrive mounts an MCP (Model Context Protocol) server at /_hyperdrive/mcp in development,
   exposing introspection tools for AI coding agents (eval Ruby, query DB, tail logs,
   list models/routes, locate source, fetch docs, snapshot stack). It also ships a
-  `hyperdrive:init` generator that discovers and installs two artifact types — lazy skills
-  and eager guidelines — shipped by companion gems under a documented contract.
+  `hyperdrive:init` generator that discovers and installs four artifact kinds — skills,
+  guidelines, agents, and commands — shipped by companion gems under a documented contract.
   rails-hyperdrive is the mechanism; companion gems (rails-hyperdrive-<library>) are the content.
 email:
 - afaceisnomore@gmail.com
@@ -93,7 +93,9 @@ files:
 - lib/generators/hyperdrive/sync/USAGE
 - lib/generators/hyperdrive/sync/sync_generator.rb
 - lib/generators/hyperdrive/sync_runner.rb
+- lib/hyperdrive/skill_tasks.rb
 - lib/rails-hyperdrive.rb
+- lib/rails/commands/hyperdrive/hyperdrive_command.rb
 - lib/rails/hyperdrive.rb
 - lib/rails/hyperdrive/ancestor_locator.rb
 - lib/rails/hyperdrive/artifact_status.rb
@@ -107,17 +109,18 @@ files:
 - lib/rails/hyperdrive/eager_footprint.rb
 - lib/rails/hyperdrive/engine.rb
 - lib/rails/hyperdrive/gem_manifest.rb
+- lib/rails/hyperdrive/gemspec_locator.rb
 - lib/rails/hyperdrive/index_document.rb
 - lib/rails/hyperdrive/install_layout.rb
 - lib/rails/hyperdrive/install_pipeline.rb
 - lib/rails/hyperdrive/install_plan.rb
 - lib/rails/hyperdrive/install_shell.rb
 - lib/rails/hyperdrive/lock_file.rb
+- lib/rails/hyperdrive/manifest_lint.rb
 - lib/rails/hyperdrive/mcp_server.rb
 - lib/rails/hyperdrive/resources/skill.rb
 - lib/rails/hyperdrive/resources/stack_profile.rb
 - lib/rails/hyperdrive/safety/rack_middleware.rb
-- lib/rails/hyperdrive/skill_tasks.rb
 - lib/rails/hyperdrive/skill_template.rb
 - lib/rails/hyperdrive/sql_safety.rb
 - lib/rails/hyperdrive/stack_profile.rb
@@ -132,7 +135,6 @@ files:
 - lib/rails/hyperdrive/tools/run_sql.rb
 - lib/rails/hyperdrive/tools/tail_logs.rb
 - lib/rails/hyperdrive/version.rb
-- lib/tasks/hyperdrive.rake
 homepage: https://github.com/rails-hyperdrive/rails-hyperdrive
 licenses:
 - MIT
@@ -158,6 +160,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Dev-only Rails engine that bootstraps an MCP server + skills/guidelines for
-  AI coding agents.
+summary: Dev-only Rails engine that bootstraps an MCP server + stack-matched skills,
+  guidelines, agents, and commands for AI coding agents.
 test_files: []

data/lib/rails/hyperdrive/skill_tasks.rb

@@ -1,27 +0,0 @@
-# Rake tasks for companion gem repos: add `require "rails/hyperdrive/skill_tasks"`
-# to the Rakefile. Both tasks take an optional gemspec-path argument, e.g.
-# rake "hyperdrive:skills:render[path/to/name.gemspec]".
-require "rake"
-require "rails/hyperdrive/canonical_skill_render"
-
-namespace :hyperdrive do
-  namespace :skills do
-    desc "Render each SKILL.md.erb template to its canonical static SKILL.md"
-    task :render, [:gemspec] do |_t, args|
-      written = Rails::Hyperdrive::CanonicalSkillRender.write(gemspec: args[:gemspec])
-      written.each { |r| puts "render #{r.dest}" }
-      puts "no skill templates found" if written.empty?
-    end
-
-    desc "Fail when a canonical SKILL.md is stale relative to its template"
-    task :check, [:gemspec] do |_t, args|
-      stale = Rails::Hyperdrive::CanonicalSkillRender.stale(gemspec: args[:gemspec])
-      if stale.empty?
-        puts "canonical skill files up to date"
-      else
-        stale.each { |r| warn "stale: #{r.dest}" }
-        abort "#{stale.size} canonical skill file(s) stale; run `rake hyperdrive:skills:render`"
-      end
-    end
-  end
-end

data/lib/tasks/hyperdrive.rake

@@ -1,22 +0,0 @@
-namespace :hyperdrive do
-  desc "Install Rails Hyperdrive into this app (writes .mcp.json, CLAUDE.md, skills, guidelines, mounts engine)"
-  task :init do
-    require "rails/generators"
-    require "generators/hyperdrive/install/install_generator"
-    Rails::Generators::Hyperdrive::InstallGenerator.start(ARGV.drop(1))
-  end
-
-  desc "Sync Rails Hyperdrive content (skills, guidelines, index.md, lockfile); locally-edited files are preserved — pass --merge (three-way merge), --sidecar (deliver upstream to <file>.new), or --overwrite (restore gem-shipped content)"
-  task :sync do
-    require "rails/generators"
-    require "generators/hyperdrive/sync/sync_generator"
-    Rails::Generators::Hyperdrive::SyncGenerator.start(ARGV.drop(1))
-  end
-
-  desc "Suggest uninstalled rails-hyperdrive companion gems for this app's stack (networked, cached; pass --refresh to re-query)"
-  task :discover do
-    require "rails/generators"
-    require "generators/hyperdrive/discover/discover_generator"
-    Rails::Generators::Hyperdrive::DiscoverGenerator.start(ARGV.drop(1))
-  end
-end