simple-agent-extension 0.2.1

data/lib/simple_agent_extension/cli.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "simple_agent_extension"
+
+module SimpleAgentExtension
+  # Command-line adapter for public package compilation and deployment.
+  class CLI
+    COMMANDS = {
+      "packages" => "List package names under the source root",
+      "build" => "Compile artifacts into the build root",
+      "deploy" => "Build artifacts, then deploy them to Agents",
+      "agents" => "List Agent names that can be targeted"
+    }.freeze
+
+    def self.run(arguments, output: $stdout, error: $stderr)
+      new(output: output, error: error).run(arguments)
+    end
+
+    def initialize(output:, error:)
+      @output = output
+      @error = error
+    end
+
+    def run(arguments)
+      arguments = arguments.dup
+      options = default_options
+      parser = option_parser(options)
+      parser.parse!(arguments)
+
+      return display_help(parser) if options[:help]
+
+      command = command(arguments)
+      validate_options(command, options)
+      AgentDirectoryLoader.new(options[:agent_directories]).load
+      run_command(command, options)
+      0
+    rescue OptionParser::ParseError, Error, ArgumentError, KeyError => error
+      @error.puts error.message
+      1
+    end
+
+    # Aligns the name column alone. Columns an Agent does not declare are
+    # dropped rather than padded, so no line carries trailing whitespace.
+    #
+    # @param [Array<Hash>] agents name, description, and homepage per Agent
+    # @return [Array<String>]
+    def agent_lines(agents)
+      width = agents.map { |agent| agent[:name].length }.max.to_i
+
+      agents.map do |agent|
+        [agent[:name].ljust(width), agent[:description], agent[:homepage]].compact.join("  ").rstrip
+      end
+    end
+
+    private
+
+    def default_options
+      {
+        source_root: File.expand_path("packages"),
+        build_root: File.expand_path("build"),
+        agents: [],
+        agent_directories: [],
+        force: false,
+        help: false
+      }
+    end
+
+    def option_parser(options)
+      OptionParser.new do |parser|
+        parser.banner = banner
+
+        parser.on("--source-root DIRECTORY", "Source package root (default: ./packages)") do |directory|
+          options[:source_root] = File.expand_path(directory)
+        end
+        parser.on("--build-root DIRECTORY", "Build artifact root (default: ./build)") do |directory|
+          options[:build_root] = File.expand_path(directory)
+        end
+        parser.on("--agent NAME", "Build or deploy only NAME (repeatable)") do |name|
+          options[:agents] << name
+        end
+        parser.on("--agent-dir DIRECTORY", "Load direct *.rb Agent registrations from DIRECTORY") do |directory|
+          options[:agent_directories] << directory
+        end
+        parser.on("--force", "Deploy even if an Agent is not installed") do
+          options[:force] = true
+        end
+        parser.on("-h", "--help", "Show this help") do
+          options[:help] = true
+        end
+      end
+    end
+
+    def banner
+      width = COMMANDS.keys.map(&:length).max
+      commands = COMMANDS.map { |name, summary| "    #{name.ljust(width)}  #{summary}" }
+
+      ["Usage: simple-agent-extension COMMAND [options]", "", "Commands:", *commands, "", "Options:"].join("\n")
+    end
+
+    def display_help(parser)
+      @output.puts parser
+      0
+    end
+
+    def command(arguments)
+      command = arguments.shift
+      raise ArgumentError, "missing command" unless command
+      raise ArgumentError, "unknown command: #{command}" unless COMMANDS.key?(command)
+      raise ArgumentError, "unexpected arguments: #{arguments.join(" ")}" unless arguments.empty?
+
+      command
+    end
+
+    def validate_options(command, options)
+      return unless options[:force] && command != "deploy"
+
+      raise ArgumentError, "--force is only valid for deploy"
+    end
+
+    def run_command(command, options)
+      runner = Runner.new(
+        source_root: options[:source_root],
+        build_root: options[:build_root],
+        agent_registry: AgentRegistry.default
+      )
+
+      case command
+      when "packages"
+        @output.puts runner.packages
+      when "agents"
+        @output.puts agent_lines(runner.agents)
+      when "build"
+        @output.puts runner.build(agents: options[:agents])
+      when "deploy"
+        @output.puts runner.build(agents: options[:agents])
+        print_deployments(runner.deploy(agents: options[:agents], force: options[:force]))
+      end
+    end
+
+    def print_deployments(deployments)
+      @output.puts DeploymentReport.new(deployments).lines
+    end
+  end
+end

data/lib/simple_agent_extension/collector.rb

@@ -0,0 +1,86 @@
+module SimpleAgentExtension
+  # Traverses the `<package>/<type>/` layout shared by source extensions and
+  # compiled artifacts. This is the only place that knows that layout.
+  class Collector
+    # Source metadata is agent-independent input, before Agent-specific
+    # translation. All source extensions therefore share one tree:
+    #
+    #   <source_root>/<package>/<type>/
+    #
+    # @param [String] root source package root
+    # @return [Collector] source extension collection
+    def self.source(root:)
+      new(root: root)
+    end
+
+    # Agent-specific metadata, filenames, and scope can differ. Build artifacts
+    # are partitioned by Agent before the shared package/type layout so those
+    # results remain distinct:
+    #
+    #   <build_root>/<agent>/<scope>/<package>/<type>/
+    #
+    # @param [String] root build root
+    # @param [AgentBase] agent selects one Agent's artifact subtree
+    # @param [Symbol] scope selects that Agent's shared or own artifacts
+    # @return [Collector] compiled artifact collection
+    def self.build(root:, agent:, scope:)
+      new(root: File.join(root, agent.name, scope.to_s))
+    end
+
+    # @param [String] root
+    def initialize(root:)
+      @root = root
+    end
+    attr_reader :root
+
+    # Build artifacts have no `metadata.yaml` and no name to read from it, so
+    # Deployer walks +dirs+ instead.
+    #
+    # @param [String, nil] package
+    # @param [String, nil] type
+    # @return [Array<Extensions::Base>]
+    def extensions(package: nil, type: nil)
+      dirs(package: package, type: type).map { |pkg, kind, dir|
+        Extensions.for(kind).new(
+          package: pkg,
+          dir: dir,
+          files: files(pkg, kind)
+        )
+      }
+    end
+
+    # @param [String, nil] package
+    # @param [String, nil] type
+    # @return [Array<[String, String, String]>] package, type, dir
+    def dirs(package: nil, type: nil)
+      Dir.glob(File.join(package || "*", type || "*", ""), base: root).map { |rel|
+        pkg, kind = rel.chomp("/").split("/")
+        [pkg, kind, dir(package: pkg, type: kind)]
+      }.sort
+    end
+
+    # `build/<agent>/<scope>/<pkg>/<type>/` is compile's write target too, so
+    # Compiler asks here rather than assembling the path itself.
+    #
+    # @param [String] package
+    # @param [String] type
+    # @return [String]
+    def dir(package:, type:)
+      File.join(root, package, type)
+    end
+
+    private
+
+    # @param [String] package
+    # @param [String] type
+    # @return [Array<String>] paths relative to +dir+
+    def files(package, type)
+      base = dir(package: package, type: type)
+
+      Dir.glob("**/*", base: base)
+        .select { |path| File.file?(File.join(base, path)) }
+        .reject { |path| path == MetadataLoader::FILENAME }
+        .sort
+    end
+  end
+end

data/lib/simple_agent_extension/compiler.rb

@@ -0,0 +1,185 @@
+require "fileutils"
+
+module SimpleAgentExtension
+  # Writes one source extension to `build/<agent>/<scope>/<pkg>/<type>/` for
+  # the configured Agent. It first resolves entrypoint metadata and artifact
+  # scope, then writes the artifact core file and its bundled files.
+  #
+  # The resulting scope has these meanings:
+  #
+  #  [source package] -> (compile) -> shared skill/ (scope)
+  #                                -> agent dir A/  (scope)
+  #                                    +-- skills/  (type)
+  #                                         +- <pkg>/
+  #                                    +-- agents/  (type)
+  #                                         +- <pkg>/
+  #                                -> agent dir B/
+  #
+  # - `shared` is a skill with no agent-specific representation or metadata.
+  # - `own` is material for one agent's configuration tree. A skill becomes
+  #
+  #   own when its representation or named metadata differs; an agent is
+  #   always own because it has no shared destination.
+  #
+  # The scope is recorded in the build path so Deployer can map the artifact
+  # to a destination without rereading source or reapplying these rules.
+  class Compiler
+    FragmentTransporter = Data.define(
+      :overlaid_adaptive,
+      :common_static,
+      :agent_static
+    )
+
+    # @param [AgentBase] agent supplies translation, core-file, and deployment facts
+    # @param [String] build_root forwarded to Collector.build
+    def initialize(agent:, build_root:)
+      @agent = agent
+      @metadata_composer = MetadataComposer.new
+      @build_root = build_root
+    end
+
+    # @param [Extensions::Base] extension
+    # @return [String]
+    def compile(extension)
+      document = extension.entrypoint_document
+      dto = fragment_transporter(
+        loader: extension.metadata_loader,
+        document: document,
+        extension_name: extension.name
+      )
+
+      adapted_fragments = translate_for_agent(
+        type: extension.type,
+        overlaid_adaptive: dto.overlaid_adaptive
+      )
+      # A named distribution target rules out the shared destination before
+      # the content has any say: that destination is read by every Agent.
+      artifact_scope = if extension.deploy_to
+        :own
+      else
+        classify_artifact_scope(
+          type: extension.type,
+          overlaid_adaptive: dto.overlaid_adaptive,
+          adapted: adapted_fragments,
+          agent_static: dto.agent_static
+        )
+      end
+      artifact_metadata = @metadata_composer.overlay_agent_specific(
+        common: dto.common_static,
+        adapted: adapted_fragments,
+        agent_static: dto.agent_static
+      )
+      materialize_artifact(
+        extension,
+        body: document.body,
+        metadata: artifact_metadata,
+        artifact_scope: artifact_scope
+      )
+    end
+
+    # A shared artifact is valid only when the Agent supports sharing,
+    # adaptation leaves its metadata unchanged, and no Agent-specific static
+    # metadata is configured. Common static metadata does not affect this decision because it
+    # applies to every Agent.
+    #
+    # @param [String, Symbol] type
+    # @param [Metadata] overlaid_adaptive adaptive source fragments with extension identity applied
+    # @param [Metadata] adapted metadata after Agent translation
+    # @param [Metadata] agent_static
+    # @return [Symbol] :shared or :own
+    def classify_artifact_scope(type:, overlaid_adaptive:, adapted:, agent_static:)
+      return :own unless @agent.deployment.shared?(type)
+      return :own unless adapted == overlaid_adaptive && agent_static.empty?
+
+      :shared
+    end
+
+    # @param [MetadataLoader] loader
+    # @param [EntrypointDocument] document
+    # @param [String] extension_name
+    # @return [FragmentTransporter]
+    def fragment_transporter(loader:, document:, extension_name:)
+      FragmentTransporter.new(
+        overlaid_adaptive: overlaid_adaptive(
+          adaptive: loader.adaptive,
+          name: extension_name
+        ),
+        common_static: @metadata_composer.common_static_fragments(
+          frontmatter: document.metadata,
+          common_static: loader.common_static
+        ),
+        agent_static: loader.agent_static(@agent.name)
+      )
+    end
+
+    # @param [String, Symbol] type
+    # @param [Metadata] overlaid_adaptive
+    # @return [Metadata]
+    def translate_for_agent(type:, overlaid_adaptive:)
+      fragments = overlaid_adaptive.each_with_object({}) do |(field, value), output|
+        fragment =
+          if @agent.can_trans_meta?(type: type, field: field)
+            @agent.trans_meta(type: type, field: field, value: value)
+          else
+            {field => value}
+          end
+        output.merge!(fragment) if fragment
+      end
+
+      Metadata.from(fragments)
+    end
+
+    private
+
+    # Overlays adaptive source fragments on extension identity before field-by-field
+    # Agent processing.
+    #
+    # @param [Metadata] adaptive
+    # @param [String] name
+    # @return [Metadata]
+    def overlaid_adaptive(adaptive:, name:)
+      Metadata.from("name" => name).merge(adaptive)
+    end
+
+    # @param [Extensions::Base] extension
+    # @param [String] body
+    # @param [Metadata] metadata
+    # @param [Symbol] artifact_scope
+    # @return [String]
+    def materialize_artifact(extension, body:, metadata:, artifact_scope:)
+      dir = Collector.build(root: @build_root, agent: @agent,
+        scope: artifact_scope)
+        .dir(package: extension.package, type: extension.type)
+      artifact_core_file = @agent.artifact_core_file(
+        extension_type: extension.type,
+        extension_name: extension.name,
+        source_file: extension.entrypoint
+      )
+
+      FileUtils.rm_rf(dir)
+      write(File.join(dir, artifact_core_file), Frontmatter.render(metadata, body))
+      copy_bundled_files(extension, dir: dir, artifact_core_file: artifact_core_file)
+
+      dir
+    end
+
+    # @param [Extensions::Base] extension
+    # @param [String] dir
+    # @param [String] artifact_core_file
+    def copy_bundled_files(extension, dir:, artifact_core_file:)
+      (extension.files - [extension.entrypoint]).each do |file|
+        copy(File.join(extension.dir, file), File.join(dir, File.dirname(artifact_core_file), file))
+      end
+    end
+
+    def write(path, text)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, text)
+    end
+
+    def copy(src, dest)
+      FileUtils.mkdir_p(File.dirname(dest))
+      FileUtils.cp(src, dest)
+    end
+  end
+end

data/lib/simple_agent_extension/deployer.rb

@@ -0,0 +1,60 @@
+require "fileutils"
+
+module SimpleAgentExtension
+  # Maps `build/<agent>/<scope>/<pkg>/<type>/` to the directories an Agent
+  # exposes, then copies it. The build scope is Compiler's recorded decision:
+  #
+  # - skill + shared -> Agent#shared_skill_dir
+  # - skill + own    -> the Agent's config-dir skill location
+  # - agent + own    -> the Agent's config-dir agent location
+  #
+  # `agent + shared` is not a valid build artifact. Deployer never examines
+  # source metadata or recomputes scope.
+  class Deployer
+    # @return [Array<String>]
+    SCOPES = %i[shared own].freeze
+
+    # @param [AgentBase] agent supplies a deployment facet
+    # @param [String] build_root forwarded to Collector.build
+    def initialize(agent:, build_root:)
+      @agent = agent
+      @build_root = build_root
+    end
+
+    # @param [Boolean] force deploy even when the Agent product is not installed
+    # @return [Array<Array(String, String)>] source and destination pairs
+    def deploy(force: false)
+      return skip_uninstalled_agent unless force || @agent.installed?
+
+      SCOPES.flat_map { |scope|
+        Collector.build(root: @build_root, agent: @agent, scope: scope).dirs.flat_map { |_pkg, type, dir|
+          copy(dir, type, scope)
+        }
+      }
+    end
+
+    private
+
+    def skip_uninstalled_agent
+      warn "skipped deployment for uninstalled agent: #{@agent.name} (#{@agent.config_dir})"
+      []
+    end
+
+    # @param [String] dir `<type>/` directory in the build tree
+    # @param [String] type
+    # @param [Symbol] scope
+    # @return [Array<Array(String, String)>]
+    def copy(dir, type, scope)
+      Dir.children(dir).map { |entry|
+        src = File.join(dir, entry)
+        dest = File.join(@agent.deployment.destination(type, scope), entry)
+
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.rm_rf(dest)
+        FileUtils.cp_r(src, dest)
+
+        [src, dest]
+      }
+    end
+  end
+end

data/lib/simple_agent_extension/deployment_report.rb

@@ -0,0 +1,52 @@
+module SimpleAgentExtension
+  # Renders `Runner#deploy` results for humans: an Agent heading, then one
+  # line per deployed extension rather than per file.
+  #
+  #   opencode
+  #     deep-review/agent -> ~/.config/opencode/agents
+  #     deep-review/skill -> ~/.agents/skills
+  #
+  # The `<package>/<type>` label comes from the build tree, so the Agent
+  # specific filename an extension was compiled into never shows up here.
+  class DeploymentReport
+    INDENT = "  "
+
+    # @param [Hash{String => Array<Array(String, String)>}] deployments
+    #   source and destination pairs per Agent name
+    # @param [String] home replaced by `~` in displayed destinations
+    def initialize(deployments, home: Dir.home)
+      @deployments = deployments
+      @home = home
+    end
+
+    # @return [Array<String>]
+    def lines
+      @deployments.flat_map { |agent_name, pairs| [agent_name, *extension_lines(pairs)] }
+    end
+
+    private
+
+    def extension_lines(pairs)
+      pairs.map { |source, destination|
+        "#{INDENT}#{extension_label(source)} -> #{shorten(File.dirname(destination))}"
+      }.uniq
+    end
+
+    # @param [String] source `.../<package>/<type>/<entry>` in the build tree
+    # @return [String]
+    def extension_label(source)
+      File.split(File.dirname(source)).map { |part| File.basename(part) }.join("/")
+    end
+
+    # Destinations are directories under an Agent's config or shared skill
+    # root, so home itself is never one of them.
+    #
+    # @param [String] path absolute destination directory
+    # @return [String]
+    def shorten(path)
+      return path unless path.start_with?("#{@home}/")
+
+      path.sub(@home, "~")
+    end
+  end
+end

data/lib/simple_agent_extension/extensions/agent.rb

@@ -0,0 +1,23 @@
+module SimpleAgentExtension
+  module Extensions
+    class Agent < Base
+      # Found rather than derived from the name: in the build tree the name is
+      # read from this very file's frontmatter, and deriving it would close a
+      # loop.
+      #
+      # @return [String]
+      def entrypoint
+        candidates = files.select { |path|
+          File.dirname(path) == "." && File.extname(path) == ".md"
+        }
+
+        unless candidates.size == 1
+          raise AmbiguousEntrypoint,
+            "expected exactly one top level .md in #{dir}, got #{candidates.inspect}"
+        end
+
+        candidates.first
+      end
+    end
+  end
+end

data/lib/simple_agent_extension/extensions/base.rb

@@ -0,0 +1,73 @@
+module SimpleAgentExtension
+  module Extensions
+    EntrypointDocument = Data.define(:metadata, :body)
+
+    # An extension that owns loading metadata from its directory.
+    class Base
+      # @param [String] package
+      # @param [String] dir directory holding the extension, source or build
+      # @param [Array<String>] files paths relative to +dir+
+      def initialize(package:, dir:, files:)
+        @package = package
+        @dir = dir
+        @files = files
+      end
+      attr_reader :package, :dir, :files
+
+      # @return [Metadata] source YAML mapping
+      def metadata
+        metadata_loader.metadata
+      end
+
+      # @return [String]
+      def type
+        self.class.name.split("::").last.downcase
+      end
+
+      # The name the extension is deployed under.
+      #
+      # prefer metadata.yaml over document frontmatter
+      #
+      # @return [String]
+      def name
+        metadata["name"] || entrypoint_document.metadata["name"] || package
+      end
+
+      # @return [String] relative to +dir+
+      def entrypoint
+        raise NotImplementedError
+      end
+
+      # @return [String]
+      def entrypoint_path
+        File.join(dir, entrypoint)
+      end
+
+      # @return [EntrypointDocument]
+      def entrypoint_document
+        metadata, body = Frontmatter.parse(File.read(entrypoint_path))
+
+        EntrypointDocument.new(metadata, body)
+      end
+
+      # @return [MetadataLoader] source YAML reader
+      def metadata_loader
+        @metadata_loader ||= MetadataLoader.load(dir)
+      end
+
+      # @return [Array<String>, nil] Agent names this extension is distributed
+      #   to; nil when it names none and therefore reaches every Agent
+      def deploy_to
+        metadata_loader.deploy_to
+      end
+
+      # @param [String] agent_name
+      # @return [Boolean]
+      def deployable_to?(agent_name)
+        names = deploy_to
+
+        names.nil? || names.include?(agent_name)
+      end
+    end
+  end
+end

data/lib/simple_agent_extension/extensions/skill.rb

@@ -0,0 +1,10 @@
+module SimpleAgentExtension
+  module Extensions
+    class Skill < Base
+      # @return [String]
+      def entrypoint
+        "SKILL.md"
+      end
+    end
+  end
+end

data/lib/simple_agent_extension/extensions.rb

@@ -0,0 +1,29 @@
+module SimpleAgentExtension
+  # Distributables. One `<pkg>/<type>/` directory is one extension.
+  #
+  # The class is the type; there is no separate attribute for it.
+  # Extension::Something ( eg, Skill, Agent, .. )
+  module Extensions
+  end
+end
+
+require_relative "extensions/base"
+require_relative "extensions/skill"
+require_relative "extensions/agent"
+
+module SimpleAgentExtension
+  module Extensions
+    # Raises a plain KeyError for an unknown type: the collector walks the
+    # second level of `packages/` unconditionally, so a directory that is not
+    # one of these is a layout mistake, not something to route around
+    #
+    # @param [String, Symbol] type
+    # @return [Class] - subclass of Extensions::Base
+    def self.for(type)
+      constants.map { |const| const_get(const) }
+        .select { |klass| klass.is_a?(Class) && klass < Base }
+        .find { |klass| klass.name.split("::").last.downcase == type.to_s } ||
+        raise(KeyError, "key not found: #{type.inspect}")
+    end
+  end
+end