simple-agent-extension 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5b57957c947b2f4c126dca54b41f69e67d8d2cbfc3a9447a31bea468b03cf76
-  data.tar.gz: 2aafa730f3def389acfd18c2cec0807dfcd78aa1148199ca7a6129ab93fe7c49
+  metadata.gz: 9ab373fc18955bd0baacc40937dcb56758ef1868b628761e9f718c0f92b85f8f
+  data.tar.gz: e059df069d89a8097aa6f08acc9f2dff02c32ebd2adce5b083e34fe0fcd722a3
 SHA512:
-  metadata.gz: 6bcc677fcc9c6afe8f01f67e77b7a65e86fda1a45ea951a21a362eb88e8b3650ec34e90399292cb3b9b0dacdb082e8c8a5ea3bc0033dbf13f3476366ed4491f2
-  data.tar.gz: f86cf67049dbc0bb7c16ed8c708ebb2e4b6c903240f1f260a2d88eb4be75e8a60c3922550ac1c99962393f5dcacee17c6c6c2ea72780a890f304b4e6d9c78bbd
+  metadata.gz: a88591dbccfda4b2e5abf84fcb2861cd35151dea90574e93b081d0c568a3eb11e6357df7726c3dd857fd4de6bf49f0eaf5651ad1c24bee910120ac32794647a3
+  data.tar.gz: 4df63619203ce861896717301521835f0261a38b97b466ed4f4ee1a3a4cb2c0ffc3a3993b6b8d75d8e5482e4f9c376ed973f1045252dd9c8a9cacc3f327dd516

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.2.2] 2026-10-04
+
+- fix: make the causes of errors easier to read
+- chore: add gem package task
+- docs: install from rubygems.org or run with rvx
+
 ## [0.2.1] 2026-10-02
 
 - feat: support Claude Code

data/README.md

@@ -4,14 +4,14 @@
 
 ## Installation
 
-Requires Ruby 3.3 or later.
+Requires Ruby 3.3 or later (not needed beforehand when running with `rvx`, which provides Ruby itself).
 
-The gem is not published to RubyGems.org yet, so install it from GitHub with Bundler:
+Add the gem to your Gemfile:
 
 ```ruby
 # Gemfile
 group :development do
-  gem "simple-agent-extension", github: "colorfulcompany/simple-agent-extension"
+  gem "simple-agent-extension"
 end
 ```
 
@@ -25,16 +25,12 @@ Then run the CLI through Bundler:
 bundle exec simple-agent-extension packages
 ```
 
-Pin a release with `tag:` so the checkout does not move:
+Or run it without a Gemfile with [rv](https://github.com/spinel-coop/rv)'s `rvx`, which installs the gem on first use:
 
-```ruby
-gem "simple-agent-extension",
-  github: "colorfulcompany/simple-agent-extension",
-  tag: "v0.1.0"
+```sh
+rvx simple-agent-extension packages
 ```
 
-`branch:` and `ref:` are also available; note that `branch:` follows new commits rather than pinning.
-
 ## Usage
 
 ### Defining a package

data/lib/simple_agent_extension/agent_directory_loader.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module SimpleAgentExtension
-  class InvalidAgentDirectory < Error; end
+  class AgentDirectoryNotFound < Error; end
+  class AgentDirectoryNotDirectory < Error; end
+  class AgentDirectoryNotReadable < Error; end
   class MissingAgentRegistration < Error; end
   class UnloadableAgentRegistration < Error; end
 
@@ -28,12 +30,15 @@ module SimpleAgentExtension
       @directories.map { |directory| canonical_directory(directory) }.uniq
     end
 
+    # The error class names the condition, so the message carries the path
+    # alone.
     def canonical_directory(directory)
       path = File.expand_path(directory)
-      raise InvalidAgentDirectory, "invalid agent directory: #{path}" unless File.directory?(path)
+      raise AgentDirectoryNotFound, path unless File.exist?(path)
+      raise AgentDirectoryNotDirectory, path unless File.directory?(path)
 
       path = File.realpath(path)
-      raise InvalidAgentDirectory, "invalid agent directory: #{path}" unless File.readable?(path)
+      raise AgentDirectoryNotReadable, path unless File.readable?(path)
 
       path
     end

data/lib/simple_agent_extension/cli.rb

@@ -6,6 +6,13 @@ require "simple_agent_extension"
 module SimpleAgentExtension
   # Command-line adapter for public package compilation and deployment.
   class CLI
+    # The command line itself was written wrong. The message describes the
+    # mistake in full, so where it was raised tells the caller nothing.
+    class UsageError < Error; end
+
+    # No command was resolved, so the caller still needs the vocabulary.
+    class CommandError < UsageError; end
+
     COMMANDS = {
       "packages" => "List package names under the source root",
       "build" => "Compile artifacts into the build root",
@@ -22,6 +29,12 @@ module SimpleAgentExtension
       @error = error
     end
 
+    # Only errors this CLI defines, and the one OptionParser raises for a
+    # misspelled option, are reduced to a message. Everything else passes
+    # through with its class, origin, and backtrace intact.
+    #
+    # CommandError has to be listed first: it is a UsageError, so the wider
+    # clause would take it otherwise.
     def run(arguments)
       arguments = arguments.dup
       options = default_options
@@ -35,9 +48,10 @@ module SimpleAgentExtension
       AgentDirectoryLoader.new(options[:agent_directories]).load
       run_command(command, options)
       0
-    rescue OptionParser::ParseError, Error, ArgumentError, KeyError => error
-      @error.puts error.message
-      1
+    rescue CommandError => error
+      report_failure(error, usage: parser)
+    rescue OptionParser::ParseError, UsageError => error
+      report_failure(error)
     end
 
     # Aligns the name column alone. Columns an Agent does not declare are
@@ -55,6 +69,16 @@ module SimpleAgentExtension
 
     private
 
+    # @param [Exception] error
+    # @param [OptionParser, nil] usage printed when the caller still needs the
+    #   command vocabulary
+    # @return [Integer] exit status the run reports as a failure
+    def report_failure(error, usage: nil)
+      @error.puts error.message
+      @error.puts usage if usage
+      1
+    end
+
     def default_options
       {
         source_root: File.expand_path("packages"),
@@ -105,9 +129,9 @@ module SimpleAgentExtension
 
     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?
+      raise CommandError, "missing command" unless command
+      raise CommandError, "unknown command: #{command}" unless COMMANDS.key?(command)
+      raise CommandError, "unexpected arguments: #{arguments.join(" ")}" unless arguments.empty?
 
       command
     end
@@ -115,7 +139,7 @@ module SimpleAgentExtension
     def validate_options(command, options)
       return unless options[:force] && command != "deploy"
 
-      raise ArgumentError, "--force is only valid for deploy"
+      raise UsageError, "--force is only valid for deploy"
     end
 
     def run_command(command, options)

data/lib/simple_agent_extension/extensions/base.rb

@@ -1,5 +1,8 @@
 module SimpleAgentExtension
   module Extensions
+    class EntrypointDocumentNotFound < Error; end
+    class InvalidEntrypointFrontmatter < Error; end
+
     EntrypointDocument = Data.define(:metadata, :body)
 
     # An extension that owns loading metadata from its directory.
@@ -48,6 +51,12 @@ module SimpleAgentExtension
         metadata, body = Frontmatter.parse(File.read(entrypoint_path))
 
         EntrypointDocument.new(metadata, body)
+      rescue Errno::ENOENT => e
+        not_found = EntrypointDocumentNotFound.new("entrypoint of package `#{@package}' / type `#{type}', #{entrypoint_path} not found.")
+        not_found.set_backtrace(e.backtrace)
+        raise not_found, cause: nil
+      rescue Psych::SyntaxError => e
+        raise InvalidEntrypointFrontmatter, "#{entrypoint_path}: #{[e.problem, e.context].compact.join(" ")} at line #{e.line + Frontmatter::METADATA_START_LINE_OFFSET} column #{e.column}", cause: nil
       end
 
       # @return [MetadataLoader] source YAML reader

data/lib/simple_agent_extension/frontmatter.rb

@@ -13,6 +13,8 @@ module SimpleAgentExtension
   module Frontmatter
     DELIMITER = "---".freeze
     PATTERN = /\A---\r?\n(.*?)^---[ \t]*\r?\n?/m
+    # Metadata starts after the opening delimiter line.
+    METADATA_START_LINE_OFFSET = 1
 
     class InvalidFrontmatter < Error; end
 

data/lib/simple_agent_extension/metadata_loader.rb

@@ -8,15 +8,23 @@ module SimpleAgentExtension
   # reader exposes adaptive, common static, and Agent-specific static fragment
   # collections without defining their field vocabulary.
   class MetadataLoader
+    class InvalidMetadata < Error; end
+
     FILENAME = "metadata.yaml".freeze
 
+    # Psych does not know which file it parsed, so the path is attached here.
+    # Its backtrace points into Psych itself, so it is dropped.
+    #
     # @param [String] dir
     # @return [MetadataLoader] empty when +metadata.yaml+ is absent, never nil
+    # @raise [InvalidMetadata] when +metadata.yaml+ has a YAML syntax error
     def self.load(dir)
       path = File.join(dir, FILENAME)
       return new(Metadata.new) unless File.exist?(path)
 
       new(Metadata.from(YAML.safe_load(File.read(path)) || {})) # rubocop:disable Style/YAMLFileRead
+    rescue Psych::SyntaxError => e
+      raise InvalidMetadata, "#{path}: #{[e.problem, e.context].compact.join(" ")} at line #{e.line} column #{e.column}", cause: nil
     end
 
     # @param [Metadata] metadata source YAML mapping

data/lib/simple_agent_extension/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleAgentExtension
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple-agent-extension
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - ''
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies: []
 description: 'Coding Agent Extension Utility with Simple DSL and Rule Translating
   and Deploying '