prompt_manager 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ffbc06761a515acea5e843fefe10ac6df3cec9d3daf88dcca7f3696c700f07
-  data.tar.gz: da7892847261aec52d5db4807eb0d27d27e5a51611bb286e25dfdc24e7a6fb55
+  metadata.gz: 8f6339dd195179a1d9d9f996d1dfc4d0c689a3ed4bb9415fe2d5d68eaaa761ba
+  data.tar.gz: 2b443af6d4ea259fd124c6ff9d225129d0e233fbffc0d9e86a42ce2189595f29
 SHA512:
-  metadata.gz: a6b73bd17ff08c89658179a86ca6e69c22646119561d3339bb3f6204a61f9c249cc0acd34c48f049bb191689c72a52e66bc9565061482e0db29a36fea3ab6e38
-  data.tar.gz: fa017dfaf15bb2da2cb37407f1308e92031bd0ae28d26caef6e9d76e5a5056511efa1324e1f50a7e7116e5e93f26f0d6d9fd802d047d5ceb98585d646ae805d1
+  metadata.gz: 26ec66ace02ff31ced22d3bd331884c0c74d5ee7356e138897759ed70be2be7d52dca239d3f1ac30c6599c8133446d199db7833de18fda7053e6fc977a1bde3b
+  data.tar.gz: a60049ad709699ec112b43c6f281dd50ae6b80d3774c5c9a58e56d6daebcb5ccfc647544461f62f3f6e4a23367421d1401b34988ae22657764b72bf387c03ff8

data/CHANGELOG.md

@@ -1,4 +1,16 @@
-## Unreleased
+### [1.0.1] - 2026-02-04
+
+#### Added
+- **`PM::Directive` base class** — class-based DSL for defining directive categories. Use `desc` before method definitions to mark them as directives, and `alias_method` for aliases. Subclass tracking, `register_all`, `category_name`, and `build_dispatch_block` are all built-in.
+- **Built-in `insert` directive** (alias: `read`) — insert any file's raw content into a prompt. Unlike `include`, the inserted content is not parsed, shell-expanded, or ERB-rendered.
+- New test file `directive_base_test.rb` with tests for the `PM::Directive` DSL, subclass tracking, category naming, and dispatch block building.
+- New test fixtures for `insert`/`read` directive coverage.
+
+#### Changed
+- **`PM::CoreDirectives`** — built-in `include`, `insert`/`read` directives refactored as a `PM::Directive` subclass using the `desc` DSL.
+- `PM.register` directive aliases now support registration via `alias_method` in `PM::Directive` subclasses, with automatic detection via `UnboundMethod#original_name`.
+- Directive registry simplified; `PM.reset_directives!` now delegates to `PM::Directive.register_all`.
+- Updated README and documentation guides for custom directives and includes.
 
 ## Released
 ### [1.0.0] = 2026-02-03

data/README.md

@@ -14,7 +14,8 @@
 - <strong>YAML Metadata</strong> - Parse from markdown strings or files<br>
 - <strong>Conditional Shell Expansion</strong> - $ENVAR, ${ENVAR}, $(command) substitution<br>
 - <strong>Conditional ERB Templates</strong> - On-demand rendering with named parameters<br>
-- <strong>Reclusive Include System</strong> - Compose prompts from multiple files<br>
+- <strong>Recursive Include System</strong> - Compose prompts from multiple files<br>
+- <strong>Raw File Insert</strong> - Insert any file's content verbatim<br>
 - <strong>Custom Directives</strong> - Register custom methods for ERB templates<br>
 - <strong>Configurable Pipeline</strong> - Enable/disable stages per prompt or globally<br>
 - <strong>Comment Stripping</strong> - HTML comments removed before processing
@@ -190,6 +191,37 @@ Included files go through the full processing pipeline (comment stripping, metad
 
 Nested includes work — A can include B which includes C. Circular includes raise an error.
 
+### Inserting raw file content
+
+Use `insert` (or its alias `read`) to insert any file's content verbatim. Unlike `include`, the inserted content is not parsed, shell-expanded, or ERB-rendered — it appears as-is:
+
+```md
+---
+title: Code Review
+parameters:
+  feedback_style: null
+---
+Review this Ruby code:
+
+```ruby
+<%= insert 'app/models/user.rb' %>
+```
+
+Use a <%= feedback_style %> tone.
+```
+
+Paths are resolved relative to the parent file's directory (same as `include`). Absolute paths work from any context. Missing files raise an error.
+
+`insert` vs `include`:
+
+| | `insert` | `include` |
+|---|---|---|
+| File types | Any | `.md` only |
+| ERB in content | Preserved as literal text | Rendered |
+| Shell expansion | Not applied | Applied |
+| Recursion | None | Nested includes supported |
+| Metadata tracking | None | `metadata.includes` tree |
+
 After calling `to_s`, the parent's metadata has an `includes` key with a tree of what was included:
 
 ```ruby
@@ -215,10 +247,11 @@ parsed.metadata.includes
 
 ### Custom directives
 
+#### Block-based registration
+
 Register custom methods available in ERB templates:
 
 ```ruby
-PM.register(:read) { |_ctx, path| File.read(path) }
 PM.register(:env)  { |_ctx, key| ENV.fetch(key, '') }
 PM.register(:run)  { |_ctx, cmd| `#{cmd}`.chomp }
 ```
@@ -229,26 +262,45 @@ Register multiple names for the same directive (aliases):
 PM.register(:webpage, :website, :web) { |_ctx, url| fetch_page(url) }
 ```
 
-All three names call the same block. Use any of them in ERB:
+#### Class-based directives
+
+For organized groups of directives, subclass `PM::Directive`:
+
+```ruby
+class MyDirectives < PM::Directive
+  desc "Fetch environment variable"
+  def env(ctx, key)
+    ENV.fetch(key, '')
+  end
+
+  desc "Run a shell command"
+  def run(ctx, cmd)
+    `#{cmd}`.chomp
+  end
+  alias_method :exec, :run
+end
 
-```markdown
-<%= webpage 'https://example.com' %>
-<%= website 'https://example.com' %>
-<%= web 'https://example.com' %>
+# Register all directive subclasses with PM
+PM::Directive.register_all
 ```
 
-Use them in any prompt file:
+`desc` marks the next method as a directive. Methods without `desc` are helpers and won't be registered. `alias_method` aliases are detected automatically.
 
-```md
----
-title: Deploy Prompt
----
-Hostname: <%= read '/etc/hostname' %>
-Environment: <%= env 'DEPLOY_ENV' %>
-Recent commits: <%= run 'git log --oneline -5' %>
+Override `build_dispatch_block` on your base class to customize how methods are called:
+
+```ruby
+class MyDirectives < PM::Directive
+  class << self
+    def build_dispatch_block(inst, method_name)
+      proc { |_ctx, *args| inst.send(method_name, args) }
+    end
+  end
+end
 ```
 
-The first argument to every directive block is a `PM::RenderContext` with access to the current render state:
+#### RenderContext
+
+The first argument to every directive block (or class method) is a `PM::RenderContext`:
 
 - `ctx.directory` — directory of the file being rendered
 - `ctx.params` — merged parameter values
@@ -256,10 +308,7 @@ The first argument to every directive block is a `PM::RenderContext` with access
 - `ctx.depth` — include nesting depth
 - `ctx.included` — Set of file paths already in the include chain
 
-```ruby
-PM.register(:current_file) { |ctx| ctx.metadata.name || 'unknown' }
-PM.register(:depth) { |ctx| ctx.depth.to_s }
-```
+#### Duplicate detection and reset
 
 Registering a name that already exists raises an error:
 
@@ -272,6 +321,7 @@ Reset to built-in directives only:
 
 ```ruby
 PM.reset_directives!
+# Restores: include, insert, read
 ```
 
 ### Disabling processing stages

data/docs/guides/custom-directives.md

@@ -84,7 +84,7 @@ Remove all custom directives and restore only the built-ins:
 PM.reset_directives!
 ```
 
-After reset, only `include` is registered.
+After reset, only the built-in directives are registered: `include`, `insert`, and `read`.
 
 ## Directives in Included Files
 
@@ -107,9 +107,74 @@ PM.register(:my_helper) { |_ctx| "works" }
 PM.register('other_helper') { |_ctx| "also works" }
 ```
 
+## Class-Based Directives
+
+For organized groups of directives, subclass `PM::Directive`:
+
+```ruby
+class MyDirectives < PM::Directive
+  desc "Fetch environment variable"
+  def env(ctx, key)
+    ENV.fetch(key, '')
+  end
+
+  desc "Run a shell command"
+  def run(ctx, cmd)
+    `#{cmd}`.chomp
+  end
+  alias_method :exec, :run
+
+  # No desc — not registered as a directive
+  def helper
+    "internal"
+  end
+end
+
+PM::Directive.register_all
+```
+
+`desc` marks the next method as a directive. Methods without `desc` are ordinary helpers and won't be registered. `alias_method` aliases are detected automatically via `UnboundMethod#original_name`.
+
+### Category name
+
+The class name determines a category heading (useful for help output):
+
+```ruby
+MyDirectives.category_name  #=> "My"
+PM::CoreDirectives.category_name  #=> "Core"
+```
+
+The last segment of the class name is used, with `Directives` stripped and camelCase split.
+
+### Dispatch customization
+
+Override `build_dispatch_block` to customize how methods are called when dispatched through `PM.directives`:
+
+```ruby
+class MyDirectives < PM::Directive
+  class << self
+    # Default: proc { |ctx, *args| inst.send(method_name, ctx, *args) }
+    def build_dispatch_block(inst, method_name)
+      proc { |_ctx, *args| inst.send(method_name, args.flatten) }
+    end
+  end
+end
+```
+
+### Subclass tracking
+
+All `PM::Directive` subclasses (direct and indirect) are tracked centrally:
+
+```ruby
+PM::Directive.directive_subclasses
+#=> [PM::CoreDirectives, MyDirectives, ...]
+```
+
+`register_all` iterates this list, creates a singleton instance per subclass, and registers each described method with `PM.register`.
+
 ## Listing Directives
 
 ```ruby
 PM.directives
-#=> { include: #<Proc>, read: #<Proc>, ... }
+#=> { include: #<Proc>, insert: #<Proc>, read: #<Proc>, ... }
 ```

data/docs/guides/includes.md

@@ -134,6 +134,44 @@ Nested includes form a tree -- each entry's `includes` array contains its own ch
 
 The `includes` array is `nil` before `to_s` is called and is reset on each call.
 
+## `insert` / `read` — Raw File Insertion
+
+Use `insert` (or its alias `read`) to insert a file's content verbatim. Unlike `include`, the content is not parsed, shell-expanded, or ERB-rendered:
+
+```markdown
+---
+title: Code Review
+---
+Review this code:
+
+```ruby
+<%= insert 'src/app.rb' %>
+```
+```
+
+### Differences from `include`
+
+| | `insert` | `include` |
+|---|---|---|
+| File types | Any | `.md` only |
+| ERB in content | Preserved as literal text | Rendered |
+| Shell expansion | Not applied | Applied |
+| Recursion | None | Nested includes supported |
+| Metadata tracking | None | `metadata.includes` tree |
+
+### Path resolution
+
+Same as `include` — paths resolve relative to the parent file's directory. Absolute paths work from any context, including string-parsed prompts.
+
+### Missing files
+
+Raises an error:
+
+```ruby
+PM.parse("---\n---\n<%= insert '/no/such/file' %>").to_s
+#=> RuntimeError: insert: file not found: /no/such/file
+```
+
 ## Requirements
 
 - The `include` directive requires file context. Using it with string-parsed prompts raises an error:

data/lib/pm/core_directives.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# lib/pm/core_directives.rb
+#
+# PM's built-in directives: include, insert/read.
+# Defined as a PM::Directive subclass using the desc/alias DSL.
+
+module PM
+  class CoreDirectives < Directive
+    desc "Include and render another prompt file"
+    def include(ctx, path)
+      unless ctx.directory
+        raise 'include requires a file context (use PM.parse with a file path)'
+      end
+
+      full_path = File.expand_path(path, ctx.directory)
+
+      if ctx.included.include?(full_path)
+        raise "Circular include detected: #{full_path}"
+      end
+
+      child  = PM.parse(full_path)
+      result = child.render_with(ctx.params, ctx.included, ctx.depth + 1)
+
+      ctx.metadata.includes << {
+        path:     full_path,
+        depth:    ctx.depth + 1,
+        metadata: child.metadata.to_h.reject { |k, _| k == :includes },
+        includes: child.metadata.includes
+      }
+
+      result
+    end
+
+    desc "Insert a file's raw content verbatim (no ERB, no shell expansion)"
+    def insert(ctx, path)
+      full_path = if ctx&.directory
+                    File.expand_path(path, ctx.directory)
+                  else
+                    File.expand_path(path)
+                  end
+
+      unless File.exist?(full_path)
+        raise "insert: file not found: #{full_path}"
+      end
+
+      File.read(full_path)
+    end
+    alias_method :read, :insert
+  end
+end

data/lib/pm/directive.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# lib/pm/directive.rb
+#
+# Base class for all directive categories.
+#
+# Subclass to define a category of directives. Use `desc` immediately
+# before a method definition to mark it as a directive and provide its
+# help description. Methods without a preceding `desc` are ordinary
+# helpers and will not be registered.
+#
+# Use Ruby's own `alias_method` to create directive aliases;
+# they are detected automatically via UnboundMethod#original_name.
+#
+# Example:
+#
+#   class MyDirectives < PM::Directive
+#     desc "Greet someone"
+#     def greet(ctx, name)
+#       "Hello, #{name}!"
+#     end
+#     alias_method :hi, :greet
+#   end
+#
+
+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
+        else
+          PM::Directive.directive_subclasses
+        end
+      end
+
+      # ---- Description helper -----------------------------------------------
+      # Call `desc "text"` on the line immediately before `def method_name`.
+
+      def desc(text)
+        @_pending_desc = text
+      end
+
+      # ---- Automatic metadata capture via method_added ----------------------
+
+      def method_added(method_name)
+        if @_pending_desc
+          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
+        end
+        super
+      end
+
+      # Per-subclass metadata stores (instance variables on the class object).
+
+      def directive_descriptions
+        @directive_descriptions ||= {}
+      end
+
+      def directive_aliases
+        @directive_aliases ||= {}
+      end
+
+      # ---- Category name derived from class name ----------------------------
+      # PM::CoreDirectives        --> "Core"
+      # AIA::WebAndFileDirectives --> "Web and File"
+
+      def category_name
+        name.split('::').last
+            .sub(/Directives$/, '')
+            .gsub(/([a-z])([A-Z])/, '\1 \2')
+      end
+
+      # ---- Singleton instance per subclass ----------------------------------
+      # Created by register_all, accessible for tests and state management.
+
+      def instance
+        @instance
+      end
+
+      # ---- 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.
+
+      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.
+
+      def register_all
+        PM::Directive.directive_subclasses.each do |klass|
+          next if klass.directive_descriptions.empty?
+
+          klass.instance_variable_set(:@instance, klass.new)
+          inst = klass.instance
+
+          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)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pm/directives.rb

@@ -25,37 +25,9 @@ module PM
     @directives
   end
 
-  # Clears all directives and re-registers the built-ins.
+  # Clears all directives and re-registers from PM::Directive subclasses.
   def self.reset_directives!
     @directives.clear
-    register_builtins
+    PM::Directive.register_all
   end
-
-  # --- Built-in directives ---
-
-  def self.register_builtins
-    register(:include) do |ctx, path|
-      unless ctx.directory
-        raise 'include requires a file context (use PM.parse with a file path)'
-      end
-      full_path = File.expand_path(path, ctx.directory)
-      if ctx.included.include?(full_path)
-        raise "Circular include detected: #{full_path}"
-      end
-      child = PM.parse(full_path)
-      result = child.render_with(ctx.params, ctx.included, ctx.depth + 1)
-
-      ctx.metadata.includes << {
-        path:     full_path,
-        depth:    ctx.depth + 1,
-        metadata: child.metadata.to_h.reject { |k, _| k == :includes },
-        includes: child.metadata.includes
-      }
-
-      result
-    end
-  end
-  private_class_method :register_builtins
-
-  register_builtins
 end

data/lib/pm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PM
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

data/lib/pm.rb

@@ -118,4 +118,9 @@ require_relative 'pm/version'
 require_relative 'pm/metadata'
 require_relative 'pm/parsed'
 require_relative 'pm/directives'
+require_relative 'pm/directive'
+require_relative 'pm/core_directives'
 require_relative 'pm/shell'
+
+# Register built-in directives from PM::CoreDirectives
+PM::Directive.register_all

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prompt_manager
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -128,6 +128,8 @@ files:
 - docs/index.md
 - lib/pm.rb
 - lib/pm/configuration.rb
+- lib/pm/core_directives.rb
+- lib/pm/directive.rb
 - lib/pm/directives.rb
 - lib/pm/metadata.rb
 - lib/pm/parsed.rb