prompt_manager 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ffbc06761a515acea5e843fefe10ac6df3cec9d3daf88dcca7f3696c700f07
-  data.tar.gz: da7892847261aec52d5db4807eb0d27d27e5a51611bb286e25dfdc24e7a6fb55
+  metadata.gz: f2de9f9b60b1bad9884fba07f280c00316c05dbd8d5f6b86e01805e461aaf968
+  data.tar.gz: 73162b249b9676d13bdf015a7cba72949d3fe9834ff6b6441fbe452048613e04
 SHA512:
-  metadata.gz: a6b73bd17ff08c89658179a86ca6e69c22646119561d3339bb3f6204a61f9c249cc0acd34c48f049bb191689c72a52e66bc9565061482e0db29a36fea3ab6e38
-  data.tar.gz: fa017dfaf15bb2da2cb37407f1308e92031bd0ae28d26caef6e9d76e5a5056511efa1324e1f50a7e7116e5e93f26f0d6d9fd802d047d5ceb98585d646ae805d1
+  metadata.gz: eb50e40c8eeb0873a68b1d84481391a1fa7b0c8f1971a461b662b86faa101bd3fd58a584f4364f2510e9df282904e3329f64b6319a16a684020b574f3aa0f1a1
+  data.tar.gz: 20f9e743881dca244716a5e14e97a34a050e07afb6ac954122988acf0cd7fd3b9bdf20c726ab73885c1a10301cc5ccdd194bcc38c50611340b6f77c06e87d2ab

data/CHANGELOG.md

@@ -1,4 +1,21 @@
-## Unreleased
+### [1.0.2] - 2026-02-09
+
+#### Changed
+- Made `PM.parse_string` a public class method so it can be called directly for parsing strings without file-based metadata enrichment.
+
+### [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
@@ -94,6 +95,14 @@ parsed = PM.parse("---\ntitle: Hello\n---\nContent here")
 
 When given a file path, `parse` adds `directory`, `name`, `created_at`, and `modified_at` to the metadata. Both forms run the full processing pipeline.
 
+Note that `PM.parse` treats single words (e.g. `'hello'`) as prompt IDs and appends `.md` to look them up as files. To parse a single word as literal string content, use `PM.parse_string`:
+
+```ruby
+PM.parse('hello')              #=> looks for hello.md in prompts_dir
+PM.parse_string('hello')       #=> parses "hello" as string content
+PM.parse_string('Any string')  #=> always parsed as content, never as a file
+```
+
 Given a file `code_review.md`:
 
 ```md
@@ -190,6 +199,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 +255,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 +270,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`:
 
-```markdown
-<%= webpage 'https://example.com' %>
-<%= website 'https://example.com' %>
-<%= web 'https://example.com' %>
+```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
+
+# 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 +316,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 +329,7 @@ Reset to built-in directives only:
 
 ```ruby
 PM.reset_directives!
+# Restores: include, insert, read
 ```
 
 ### Disabling processing stages

data/docs/api/pm-module.md

@@ -38,6 +38,44 @@ parsed = PM.parse("---\ntitle: Hello\n---\nContent")
 
 ---
 
+### PM.parse_string(string) → Parsed
+
+Parse a string directly through the processing pipeline, bypassing all file-detection logic. Unlike `PM.parse`, single words are never treated as prompt IDs.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `string` | String | Raw string content to parse |
+
+**Returns:** `PM::Parsed` (Struct with `metadata` and `content`)
+
+**Behavior:**
+
+- Always parses the input as string content — never looks up files
+- Runs the same pipeline as `PM.parse`: strip comments → extract YAML → shell expansion
+- Does not add `directory`, `name`, `created_at`, or `modified_at` to metadata
+
+```ruby
+# Single words are parsed as content, not treated as file basenames
+parsed = PM.parse_string('hello')
+parsed.content  #=> "hello"
+
+# Strings with YAML front-matter work as expected
+parsed = PM.parse_string("---\ntitle: Hello\n---\nContent")
+parsed.metadata.title  #=> "Hello"
+parsed.content         #=> "Content\n"
+```
+
+**When to use `parse_string` instead of `parse`:**
+
+```ruby
+PM.parse('summarize')          #=> looks for summarize.md
+PM.parse_string('summarize')   #=> parses "summarize" as content
+```
+
+---
+
 ## Configuration
 
 ### PM.config → Configuration

data/docs/getting-started/quick-start.md

@@ -40,6 +40,19 @@ puts parsed.to_s('name' => 'Alice')
 
 When parsing a file, PM also adds `directory`, `name`, `created_at`, and `modified_at` to the metadata.
 
+## Parse a String Directly
+
+`PM.parse` treats single words as prompt IDs and looks them up as files. To always parse a string as content, use `PM.parse_string`:
+
+```ruby
+PM.parse('hello')              #=> looks for hello.md in prompts_dir
+PM.parse_string('hello')       #=> parses "hello" as string content
+
+parsed = PM.parse_string("---\ntitle: Inline\n---\nSome content")
+parsed.metadata.title  #=> "Inline"
+parsed.content         #=> "Some content\n"
+```
+
 ## Parameters
 
 Parameters declared in the YAML front-matter define template variables:

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/docs/guides/parsing.md

@@ -69,6 +69,30 @@ String-parsed prompts do not have `directory`, `name`, `created_at`, or `modifie
 !!! warning "Include limitations"
     The `include` directive requires file context to resolve relative paths. It raises an error when used with string-parsed prompts.
 
+### PM.parse_string vs PM.parse
+
+Because `PM.parse` treats single words as prompt IDs (appending `.md` and looking them up as files), short strings like `"hello"` or `"summarize"` will trigger a file lookup instead of being parsed as content. Use `PM.parse_string` to always parse a string as content:
+
+```ruby
+# PM.parse treats single words as prompt IDs
+PM.parse('hello')          #=> looks for hello.md in prompts_dir
+PM.parse('summarize')      #=> looks for summarize.md in prompts_dir
+
+# PM.parse_string always parses as string content
+PM.parse_string('hello')          #=> Parsed with content "hello"
+PM.parse_string('summarize')      #=> Parsed with content "summarize"
+
+# Multi-word strings without .md extension work the same in both
+PM.parse("Hello world")           #=> Parsed with content "Hello world"
+PM.parse_string("Hello world")    #=> Parsed with content "Hello world"
+```
+
+Use `PM.parse_string` when:
+
+- Your input may be a single word that should not be treated as a file
+- You know the source is always a string, never a file path
+- You want to skip the file-detection logic entirely
+
 ## Metadata Extraction
 
 YAML front-matter is delimited by `---` fences:

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.2'
 end

data/lib/pm.rb

@@ -98,7 +98,7 @@ module PM
 
     Parsed.new(metadata: metadata, content: content)
   end
-  private_class_method :parse_string
+
 
   # Builds a Metadata object with defaults for shell and erb.
   def self.build_metadata(hash)
@@ -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.2
 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
@@ -157,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.5
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Parse YAML metadata from markdown prompts with shell expansion and ERB rendering
 test_files: []