prompt_manager 1.0.2 → 1.2.0

data/lib/pm/directive.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# lib/pm/directive.rb
-#
 # Base class for all directive categories.
 #
 # Subclass to define a category of directives. Use `desc` immediately
@@ -22,26 +20,21 @@
 #     alias_method :hi, :greet
 #   end
 #
+#   PM::Directive.register_all
 
 module PM
   class Directive
     # Centralized list of all subclasses across the hierarchy.
-    # Initialized here on PM::Directive; the inherited hook always
-    # appends to this specific array.
     @directive_subclasses = []
 
     class << self
       # ---- Subclass tracking ------------------------------------------------
-      # Every subclass (direct or indirect) is tracked in PM::Directive's
-      # centralized list so register_all can find them all.
 
       def inherited(subclass)
         PM::Directive.directive_subclasses << subclass
         super
       end
 
-      # Returns the centralized subclass list.  Only meaningful when called
-      # on PM::Directive itself; subclasses delegate here explicitly.
       def directive_subclasses
         if equal?(PM::Directive)
           @directive_subclasses
@@ -64,23 +57,12 @@ module PM
           directive_descriptions[method_name] = @_pending_desc
           @_pending_desc = nil
         else
-          # Detect aliases created by alias_method.
-          # UnboundMethod#original_name returns the original method name;
-          # when it differs from method_name, this method is an alias.
-          begin
-            um = instance_method(method_name)
-            original = um.original_name
-            if original != method_name && directive_descriptions.key?(original)
-              (directive_aliases[original] ||= []) << method_name
-            end
-          rescue NameError
-            # ignore — method may reference undefined constants at load time
-          end
+          record_alias(method_name)
         end
         super
       end
 
-      # Per-subclass metadata stores (instance variables on the class object).
+      # Per-subclass metadata stores.
 
       def directive_descriptions
         @directive_descriptions ||= {}
@@ -92,7 +74,7 @@ module PM
 
       # ---- Category name derived from class name ----------------------------
       # PM::CoreDirectives        --> "Core"
-      # AIA::WebAndFileDirectives --> "Web and File"
+      # AIA::WebAndFileDirectives --> "Web And File"
 
       def category_name
         name.split('::').last
@@ -101,7 +83,6 @@ module PM
       end
 
       # ---- Singleton instance per subclass ----------------------------------
-      # Created by register_all, accessible for tests and state management.
 
       def instance
         @instance
@@ -109,16 +90,17 @@ module PM
 
       # ---- Dispatch block builder -------------------------------------------
       # Override in subclasses to customize how directive methods are called.
-      # The default passes (ctx, *args) straight through — suitable for
-      # PM::CoreDirectives whose methods use the RenderContext.
+      # The default passes (ctx, *args) straight through.
 
       def build_dispatch_block(inst, method_name)
         proc { |ctx, *args| inst.send(method_name, ctx, *args) }
       end
 
       # ---- PM registration --------------------------------------------------
-      # Creates one instance per subclass and registers every described
-      # method (plus its aliases) with PM.
+      # Creates one instance per subclass and registers every described method
+      # (plus its aliases). Safe to call repeatedly: a subclass may re-register
+      # its own names, and a later subclass may override an earlier one. A name
+      # claimed with PM.register raises DirectiveAlreadyRegisteredError.
 
       def register_all
         PM::Directive.directive_subclasses.each do |klass|
@@ -129,15 +111,25 @@ module PM
 
           klass.directive_descriptions.each_key do |method_name|
             aliases = klass.directive_aliases[method_name] || []
-            names   = [method_name, *aliases]
-
-            # Remove previously registered names (idempotent re-init)
-            names.each { |n| PM.directives.delete(n.to_sym) }
-
-            block = klass.build_dispatch_block(inst, method_name)
-            PM.register(*names, &block)
+            block   = klass.build_dispatch_block(inst, method_name)
+            PM.send(:register_from_class, klass, [method_name, *aliases], block)
           end
         end
+        nil
+      end
+
+      private
+
+      # Detects aliases created by alias_method: UnboundMethod#original_name
+      # differs from the method name when the method is an alias.
+      def record_alias(method_name)
+        um       = instance_method(method_name)
+        original = um.original_name
+        return if original == method_name || !directive_descriptions.key?(original)
+
+        (directive_aliases[original] ||= []) << method_name
+      rescue NameError
+        # The method may reference constants that are not yet defined at load time.
       end
     end
   end

data/lib/pm/directives.rb

@@ -2,32 +2,71 @@
 
 module PM
   # --- Directive registry ---
+  #
+  # Two kinds of registration share one namespace:
+  #   PM.register(:name) { |ctx, *args| ... }   -- block directives
+  #   PM::Directive subclasses + register_all   -- class directives
+  #
+  # Rules:
+  #   * PM.register raises DirectiveAlreadyRegisteredError if ANY requested name
+  #     is taken, and registers nothing in that case (atomic).
+  #   * register_all may re-register a name that a Directive subclass owns
+  #     (so it is idempotent and a later subclass can override an earlier one),
+  #     but raises if the name was claimed with PM.register.
 
-  @directives = {}
+  @directives       = {}
+  @directive_owners = {} # name => the PM::Directive subclass that registered it
 
-  # Registers one or more named directives available in ERB templates.
-  # The block receives a RenderContext as its first argument,
-  # followed by any arguments from the ERB call.
-  # Multiple names register the same block under each name (aliases).
-  # Raises RuntimeError if any name is already registered.
+  # Registers one or more names for the same block. The block receives a
+  # RenderContext first, then the arguments from the ERB call.
   def self.register(*names, &block)
-    names.each do |name|
-      name = name.to_sym
-      if @directives.key?(name)
-        raise "Directive already registered: #{name}"
-      end
-      @directives[name] = block
-    end
+    raise ArgumentError, 'PM.register requires a block' unless block
+
+    syms  = names.map(&:to_sym)
+    taken = syms.find { |name| @directives.key?(name) }
+    raise DirectiveAlreadyRegisteredError, "Directive already registered: #{taken}" if taken
+
+    syms.each { |name| @directives[name] = block }
+    nil
   end
 
-  # Returns the registered directives hash.
+  # A frozen snapshot of the registry (name => block). Mutating it has no
+  # effect on PM; use PM.register / PM.reset_directives!.
   def self.directives
-    @directives
+    @directives.dup.freeze
   end
 
-  # Clears all directives and re-registers from PM::Directive subclasses.
+  def self.directive?(name)
+    @directives.key?(name.to_sym)
+  end
+
+  # Clears every directive, then re-registers the PM::Directive subclasses.
   def self.reset_directives!
     @directives.clear
+    @directive_owners.clear
     PM::Directive.register_all
+    nil
+  end
+
+  # Used by PM::Directive.register_all. Not part of the public API.
+  def self.register_from_class(klass, names, block)
+    syms = names.map(&:to_sym)
+
+    syms.each do |name|
+      next unless @directives.key?(name)
+      if @directive_owners[name].nil?
+        raise DirectiveAlreadyRegisteredError,
+              "Directive already registered with PM.register: #{name}"
+      end
+
+      @directives.delete(name) # owned by a Directive subclass: later registration wins
+    end
+
+    syms.each do |name|
+      @directives[name]       = block
+      @directive_owners[name] = klass
+    end
+    nil
   end
+  private_class_method :register_from_class
 end

data/lib/pm/errors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module PM
+  # Base class for every error PM raises itself.
+  #
+  # Errors from the standard library pass through unchanged:
+  #   Errno::ENOENT      -- PM.parse given a file path that does not exist
+  #   Psych::SyntaxError -- front matter that is not valid YAML
+  #   Psych::DisallowedClass / Psych::AliasesNotEnabled -- YAML using symbols or anchors
+  #   SyntaxError        -- ERB that does not compile
+  class Error < StandardError; end
+
+  # Front matter was present but not a YAML mapping, or a known key
+  # (`shell`, `erb`, `parameters`) had a value of the wrong type.
+  class MetadataError < Error; end
+
+  # Shell expansion could not complete (for example an unmatched `$(`).
+  class ShellExpansionError < Error; end
+
+  # A `$(command)` exited non-zero. Carries the command, its Process::Status,
+  # and whatever it wrote to stderr.
+  class ShellCommandError < ShellExpansionError
+    attr_reader :command, :status, :stderr
+
+    def initialize(command, status, stderr = '')
+      @command = command
+      @status  = status
+      @stderr  = stderr.to_s
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      message = "Shell command failed (exit #{status.exitstatus}): #{command}"
+      detail  = stderr.strip
+      detail.empty? ? message : "#{message}\n#{detail}"
+    end
+  end
+
+  # Base for problems raised by the built-in `include` directive.
+  class IncludeError < Error; end
+
+  # A file tried to include one of its own ancestors.
+  class CircularIncludeError < IncludeError; end
+
+  # Nesting went past PM.config.max_include_depth.
+  class IncludeDepthError < IncludeError; end
+
+  # `include` was used from a string-parsed prompt that has no directory.
+  class IncludeContextError < IncludeError; end
+
+  # `insert` / `read` named a file that does not exist.
+  class FileNotFoundError < Error; end
+
+  # PM.register (or a PM::Directive subclass) tried to claim a name that is taken.
+  class DirectiveAlreadyRegisteredError < Error; end
+
+  # Parameter problems. Subclasses ArgumentError rather than PM::Error so that
+  # `rescue ArgumentError` written against 1.0.x keeps working. Rescue
+  # PM::ParameterError when you want only these.
+  class ParameterError < ArgumentError; end
+
+  # A parameter declared with a `null` default was not supplied to `to_s`.
+  # The message always starts with "Missing required parameters:".
+  class MissingParameterError < ParameterError; end
+
+  # Strict mode only: a template referenced a name that is neither a
+  # parameter nor a registered directive.
+  class UnknownParameterError < ParameterError; end
+end

data/lib/pm/metadata.rb

@@ -1,17 +1,118 @@
 # frozen_string_literal: true
 
-require 'ostruct'
-
 module PM
-  # OpenStruct-based metadata with predicate methods for boolean keys.
-  class Metadata < OpenStruct
+  # Schemaless front-matter container with dot-notation access.
+  #
+  #   meta = PM::Metadata.new('title' => 'Hi', shell: true)
+  #   meta.title      #=> "Hi"
+  #   meta[:title]    #=> "Hi"
+  #   meta['title']   #=> "Hi"
+  #   meta.shell?     #=> true     (predicates exist only for true/false values)
+  #   meta.missing    #=> nil
+  #   meta.other = 1  # setter
+  #   meta.to_h       #=> {title: "Hi", shell: true, other: 1}   (Symbol keys)
+  #
+  # Keys are stored as Symbols; `[]`, `[]=`, and `key?` accept Strings or Symbols.
+  # A key whose name collides with a public Object method (`hash`, `display`, ...)
+  # still works through dot notation because an accessor is defined for it.
+  class Metadata
+    include Enumerable
+
+    # Object methods that must never be shadowed by a metadata key.
+    PROTECTED_METHODS = %i[
+      class object_id send public_send __send__ __id__ respond_to? respond_to_missing?
+      method_missing instance_variable_get instance_variable_set instance_variables
+      is_a? kind_of? instance_of? freeze frozen? dup clone itself then tap
+      to_h to_s inspect == != equal? eql? each each_pair key? keys values
+      fetch dig delete empty? size length to_enum enum_for
+    ].to_set.freeze
+
     def initialize(hash = {})
-      super(hash)
-      hash.each do |key, value|
-        if value.is_a?(TrueClass) || value.is_a?(FalseClass)
-          define_singleton_method(:"#{key}?") { send(key) }
-        end
+      @table = {}
+      hash.each { |key, value| self[key] = value }
+    end
+
+    def [](key)
+      @table[key.to_sym]
+    end
+
+    def []=(key, value)
+      sym = key.to_sym
+      @table[sym] = value
+      define_accessor(sym) if shadows_object_method?(sym)
+      value
+    end
+
+    def key?(key) = @table.key?(key.to_sym)
+
+    def keys   = @table.keys
+    def values = @table.values
+    def size   = @table.size
+    alias length size
+    def empty? = @table.empty?
+
+    def fetch(key, *default, &block) = @table.fetch(key.to_sym, *default, &block)
+
+    def dig(key, *rest)
+      value = self[key]
+      rest.empty? || value.nil? ? value : value.dig(*rest)
+    end
+
+    def delete(key) = @table.delete(key.to_sym)
+
+    def each(&block)
+      return to_enum(:each) unless block
+
+      @table.each(&block)
+      self
+    end
+    alias each_pair each
+
+    def to_h = @table.dup
+
+    def ==(other)
+      other.is_a?(Metadata) && to_h == other.to_h
+    end
+
+    def inspect = "#<PM::Metadata #{@table.inspect}>"
+    alias to_s inspect
+
+    def method_missing(name, *args, &block)
+      key = name.to_s
+
+      if key.end_with?('=') && args.size == 1
+        self[key.chomp('=')] = args.first
+      elsif key.end_with?('?') && args.empty? && boolean_key?(key.chomp('?'))
+        self[key.chomp('?')]
+      elsif args.empty? && !key.end_with?('?', '!')
+        self[key] # nil for unknown keys, matching 1.0.x OpenStruct behaviour
+      else
+        super
       end
     end
+
+    def respond_to_missing?(name, include_private = false)
+      key = name.to_s
+      return true  if key.end_with?('=')
+      return boolean_key?(key.chomp('?')) if key.end_with?('?')
+      return false if key.end_with?('!')
+
+      key?(key) || super
+    end
+
+    private
+
+    def boolean_key?(key)
+      value = self[key]
+      value.equal?(true) || value.equal?(false)
+    end
+
+    def shadows_object_method?(sym)
+      !PROTECTED_METHODS.include?(sym) && Object.public_method_defined?(sym)
+    end
+
+    def define_accessor(sym)
+      define_singleton_method(sym) { @table[sym] }
+    end
   end
 end

data/lib/pm/parsed.rb

@@ -1,59 +1,64 @@
 # frozen_string_literal: true
 
-require 'set'
-require 'ostruct'
-require 'erb'
+require 'yaml'
 
 module PM
-  # Render context passed to registered directives.
-  RenderContext = Struct.new(:directory, :params, :included, :depth, :metadata, keyword_init: true)
-
-  Parsed = Struct.new(:metadata, :content, keyword_init: true) do
-    def [](key)
-      metadata[key]
+  # Passed as the first argument to every directive.
+  #
+  #   directory -- directory of the file being rendered (nil for string prompts)
+  #   params    -- merged parameter values (String keys)
+  #   included  -- Set of ancestor file paths, used for circular-include detection
+  #   depth     -- include nesting depth (0 for the top-level prompt)
+  #   metadata  -- the current file's PM::Metadata
+  RenderContext = Data.define(:directory, :params, :included, :depth, :metadata) do
+    def initialize(directory: nil, params: {}, included: Set.new, depth: 0, metadata: nil)
+      super(directory: directory, params: params, included: included, depth: depth, metadata: metadata)
     end
+  end
+
+  # Metadata keys PM adds itself when parsing a file, or fills in while rendering.
+  # They are left out of #to_markdown so a prompt round-trips cleanly.
+  DERIVED_METADATA_KEYS = %i[directory name created_at modified_at includes].freeze
+
+  # The result of PM.parse: front matter plus content with shell references
+  # already expanded. Call #to_s to render the ERB.
+  Parsed = Data.define(:metadata, :content) do
+    def [](key) = metadata[key]
+
+    def key?(key) = metadata.key?(key)
+
+    # The `parameters` mapping from the front matter ({} when absent).
+    def parameters = metadata.parameters || {}
 
-    # Returns the prompt content with ERB tags expanded.
-    # Registered directives are available as methods in the ERB binding.
-    # Raises if any required parameters (default: null) are not provided.
-    # When metadata has erb: false, returns content without ERB processing.
+    # Renders the content with ERB. Registered directives and parameters are
+    # available as bare identifiers. Raises PM::MissingParameterError (an
+    # ArgumentError) if a `null`-default parameter is not supplied.
+    # With `erb: false` the content is returned untouched.
     def to_s(values = {})
-      render_with(values, Set.new, 0)
+      Renderer.new(self).render(values)
     end
 
+    # Rendering entry point used by the `include` directive, which must pass
+    # the active include chain and depth through.
     def render_with(values, included, depth)
-      metadata.includes = []
-      return content unless metadata.erb?
-
-      defaults = metadata.parameters || {}
-      params = defaults.merge(values.transform_keys(&:to_s))
-
-      missing = params.select { |_, v| v.nil? }.keys
-      unless missing.empty?
-        raise ArgumentError, "Missing required parameters: #{missing.join(', ')}"
-      end
-
-      if metadata.directory && metadata.name
-        included.add(File.join(metadata.directory, metadata.name))
-      end
-
-      context = OpenStruct.new(params)
-
-      render_ctx = PM::RenderContext.new(
-        directory: metadata.directory,
-        params:    params,
-        included:  included,
-        depth:     depth,
-        metadata:  metadata
-      )
-
-      PM.directives.each do |name, block|
-        context.define_singleton_method(name) do |*args|
-          block.call(render_ctx, *args)
-        end
-      end
-
-      ERB.new(content).result(context.instance_eval { binding })
+      Renderer.new(self).render(values, included: included, depth: depth)
+    end
+
+    def to_h
+      { metadata: metadata.to_h, content: content }
+    end
+
+    # The prompt as a markdown file again: YAML front matter followed by the
+    # content. Keys PM derived from the file system (directory, name, timestamps)
+    # and the `includes` tree are omitted. `shell` and `erb` are always written,
+    # since their values were resolved against the global config at parse time.
+    # Content is the parsed content, so shell references have already been expanded.
+    def to_markdown
+      authored = metadata.to_h.reject { |key, _| DERIVED_METADATA_KEYS.include?(key) }
+      return content if authored.empty?
+
+      yaml = YAML.dump(authored.transform_keys(&:to_s)).delete_prefix("---\n")
+      "---\n#{yaml}---\n#{content}"
     end
   end
 end

data/lib/pm/render_scope.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module PM
+  # The object whose binding an ERB template is evaluated in.
+  #
+  # A bare identifier in a template resolves here, in this order:
+  #   1. a parameter of that name, when called with no arguments
+  #   2. a registered directive of that name (called with the RenderContext first)
+  #   3. nil -- or PM::UnknownParameterError when PM.config.strict_parameters is on
+  #
+  # So a parameter shadows a zero-argument directive call of the same name, and
+  # a directive call with arguments is never confused with a parameter.
+  class RenderScope
+    def initialize(params, directives, context, strict: false)
+      @params     = params
+      @directives = directives
+      @context    = context
+      @strict     = strict
+      shadow_object_methods
+    end
+
+    # The binding ERB renders in. A method rather than instance_eval so the
+    # only locals visible to the template are ERB's own.
+    def erb_binding = binding
+
+    def method_missing(name, *args, &block)
+      key = name.to_s
+
+      if args.empty? && @params.key?(key)
+        @params[key]
+      elsif (directive = @directives[name])
+        directive.call(@context, *args, &block)
+      elsif @strict
+        raise UnknownParameterError, "Unknown parameter or directive: #{name}"
+      elsif args.empty?
+        nil
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @params.key?(name.to_s) || @directives.key?(name) || super
+    end
+
+    private
+
+    # Never shadowed: erb_binding calls `binding`.
+    UNSHADOWED = %i[binding].freeze
+
+    # A parameter named like an Object method -- public (`hash`, `display`)
+    # or private Kernel (`format`, `test`, `system`) -- would otherwise never
+    # reach method_missing. Called bare it is the parameter; called with
+    # arguments or a block it is still the method.
+    def shadow_object_methods
+      @params.each_key do |key|
+        sym = key.to_sym
+        next unless shadowable?(sym)
+
+        define_singleton_method(sym) do |*args, **kwargs, &block|
+          next @params[key] if args.empty? && kwargs.empty? && block.nil?
+
+          super(*args, **kwargs, &block)
+        end
+      end
+    end
+
+    def shadowable?(sym)
+      return false if Metadata::PROTECTED_METHODS.include?(sym) || UNSHADOWED.include?(sym)
+
+      Object.public_method_defined?(sym) || Object.private_method_defined?(sym)
+    end
+  end
+end

data/lib/pm/renderer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module PM
+  # Turns a Parsed prompt into its final string: merges parameters, checks the
+  # required ones, builds the RenderContext, and evaluates ERB.
+  #
+  # `included` is the set of ancestor file paths (the active include chain).
+  # It is copied, never mutated, so sibling includes do not see each other.
+  class Renderer
+    def initialize(parsed)
+      @parsed   = parsed
+      @metadata = parsed.metadata
+    end
+
+    def render(values = {}, included: Set.new, depth: 0)
+      @metadata.includes = []
+      return @parsed.content unless @metadata.erb?
+
+      params  = merge_params(values)
+      context = build_context(params, included, depth)
+      scope   = RenderScope.new(params, PM.directives, context, strict: PM.config.strict_parameters?)
+
+      ERB.new(@parsed.content).result(scope.erb_binding)
+    end
+
+    private
+
+    def merge_params(values)
+      defaults = (@metadata.parameters || {}).transform_keys(&:to_s)
+      params   = defaults.merge(values.transform_keys(&:to_s))
+
+      missing = params.select { |_, value| value.nil? }.keys
+      raise MissingParameterError, "Missing required parameters: #{missing.join(', ')}" unless missing.empty?
+
+      params
+    end
+
+    def build_context(params, included, depth)
+      ancestors = included.dup
+      ancestors << own_path if own_path
+
+      RenderContext.new(
+        directory: @metadata.directory,
+        params:    params,
+        included:  ancestors,
+        depth:     depth,
+        metadata:  @metadata
+      )
+    end
+
+    def own_path
+      return nil unless @metadata.directory && @metadata.name
+
+      File.join(@metadata.directory, @metadata.name)
+    end
+  end
+end