prompt_manager 0.5.8 → 1.0.0

data/docs/guides/shell-expansion.md

@@ -0,0 +1,108 @@
+# Shell Expansion
+
+Shell expansion replaces environment variable references and command substitutions with their values at parse time.
+
+## Syntax
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `$VAR` | Environment variable | `$USER` |
+| `${VAR}` | Environment variable (braced) | `${HOME}` |
+| `$(command)` | Command substitution | `$(date +%Y-%m-%d)` |
+
+## Environment Variables
+
+```markdown
+---
+title: Info
+---
+Current user: $USER
+Home directory: ${HOME}
+```
+
+After parsing:
+
+```ruby
+parsed = PM.parse('info.md')
+parsed.content
+#=> "Current user: dewayne\nHome directory: /Users/dewayne\n"
+```
+
+Only UPPERCASE variable names are expanded. Lowercase names like `$foo` are left as-is.
+
+Missing environment variables are replaced with an empty string.
+
+## Command Substitution
+
+```markdown
+---
+title: Context
+---
+Date: $(date +%Y-%m-%d)
+Branch: $(git rev-parse --abbrev-ref HEAD)
+```
+
+Commands are executed via the shell and replaced with their stdout (trailing newline stripped).
+
+### Nested Commands
+
+Nested parentheses are handled correctly:
+
+```markdown
+$(echo $(echo hello))
+```
+
+### Failed Commands
+
+A command that exits with a non-zero status raises `RuntimeError`:
+
+```ruby
+PM.parse("Output: $(exit 1)")
+#=> RuntimeError: Command failed with exit status 1: exit 1
+```
+
+## Direct Access
+
+Shell expansion is available as a standalone method:
+
+```ruby
+PM.expand_shell("Hello $USER from $(hostname)")
+#=> "Hello dewayne from venus"
+```
+
+## Disabling Shell Expansion
+
+Set `shell: false` in the file's YAML metadata:
+
+```markdown
+---
+title: Raw
+shell: false
+---
+This $USER reference is preserved as-is.
+```
+
+Or disable globally:
+
+```ruby
+PM.configure { |c| c.shell = false }
+```
+
+Per-file metadata always overrides the global setting. A file with `shell: true` gets shell expansion even when the global default is `false`.
+
+## Interaction with ERB
+
+Shell expansion happens at parse time (step 3 of the pipeline). ERB rendering happens later when `to_s` is called (step 4). This means shell references in the raw template are expanded before ERB sees the content.
+
+If you need dynamic shell output at render time, use a custom directive instead:
+
+```ruby
+PM.register(:sh) { |_ctx, cmd| `#{cmd}`.chomp }
+```
+
+```markdown
+---
+title: Dynamic
+---
+Branch: <%= sh 'git rev-parse --abbrev-ref HEAD' %>
+```

data/docs/index.md

@@ -1,230 +1,70 @@
-# PromptManager Documentation
-
-<div align="center" style="background-color: #fff3cd; color: #856404; padding: 20px; margin: 20px 0; border: 2px solid #ffeaa7; border-radius: 5px; font-size: 18px; font-weight: bold;">
-  ⚠️ CAUTION ⚠️<br />
-  Breaking Changes are Coming<br />
-  See <a href="development/roadmap/">Roadmap</a> for details
-</div>
-
-<div align="center">
-  <table>
-    <tr>
-      <td width="40%" align="center" valign="top">
-        <img src="../prompt_manager_logo.png" alt="PromptManager - The Enchanted Librarian of AI Prompts" width="400">
-      </td>
-      <td width="60%" align="left" valign="top">
-        <p><strong>Like an enchanted librarian organizing floating books of knowledge, PromptManager helps you masterfully orchestrate and organize your AI prompts through wisdom and experience.</strong></p>
-        
-        <p>Each prompt becomes a living entity that can be categorized, parameterized, and interconnected with golden threads of relationships.</p>
-        
-        <h3>Key Features</h3>
-        <ul>
-            <li><strong>📚 <a href="storage/overview/">Multiple Storage Adapters</a></strong></li>
-            <li><strong>🔧 <a href="core-features/parameterized-prompts/">Parameterized Prompts</a></strong></li>
-            <li><strong>📋 <a href="core-features/directive-processing/">Directive Processing</a></strong></li>
-            <li><strong>🎨 <a href="core-features/erb-integration/">ERB Integration</a></strong></li>
-            <li><strong>🌍 <a href="core-features/shell-integration/">Shell Integration</a></strong></li>
-            <li><strong>📖 <a href="core-features/comments/">Inline Documentation</a></strong></li>
-            <li><strong>📊 <a href="core-features/parameter-history/">Parameter History</a></strong></li>
-            <li><strong>⚡ <a href="core-features/error-handling/">Error Handling</a></strong></li>
-            <li><strong>🔌 <a href="advanced/custom-keywords/">Extensible Architecture</a></strong></li>
-        </ul>
-      </td>
-    </tr>
-  </table>
-</div>
-
-## What is PromptManager?
-
-PromptManager is a Ruby gem designed for managing parameterized prompts used in generative AI applications. It provides a sophisticated system for organizing, templating, and processing prompts with support for multiple storage backends, directive processing, and advanced templating features.
-
-Think of it as your personal AI prompt librarian - organizing your prompts, managing their parameters, processing their directives, and ensuring they're always ready when you need them.
-
-## Quick Start
-
-Get up and running with PromptManager in minutes:
-
-=== "Installation"
-
-    ```bash
-    gem install prompt_manager
-    # or add to Gemfile
-    bundle add prompt_manager
-    ```
-
-=== "Basic Usage"
-
-    ```ruby
-    require 'prompt_manager'
-
-    # Configure storage
-    PromptManager::Prompt.storage_adapter = 
-      PromptManager::Storage::FileSystemAdapter.config do |config|
-        config.prompts_dir = '~/.prompts'
-      end.new
-
-    # Use a prompt
-    prompt = PromptManager::Prompt.new(id: 'greeting')
-    prompt.parameters = {
-      "[NAME]" => "Alice",
-      "[LANGUAGE]" => "English"
-    }
-    
-    puts prompt.to_s
-    ```
-
-=== "Create a Prompt"
-
-    ```text
-    # ~/.prompts/greeting.txt
-    # Description: A friendly greeting prompt
-    
-    Hello [NAME]! How can I assist you today?
-    Please respond in [LANGUAGE].
-    ```
-
-## Architecture Overview
-
-PromptManager follows a modular architecture designed for flexibility and extensibility:
+# PM (PromptManager)
+
+<table>
+<tr>
+<td width="40%" align="center" valign="top">
+  <img src="assets/images/prompt_manager.gif" alt="PromptManager" width="100%"><br>
+  <em>"Prompts with superpowers"</em>
+</td>
+<td width="60%" valign="top">
+<strong>Parse YAML metadata from markdown, expand shell references, and render ERB templates on demand</strong><br><br>
+PM (PromptManager) treats prompt files as composable, parameterized templates. Write prompts in markdown with YAML front matter, shell references, and ERB — PM handles the rest.
+
+<h3>Key Features</h3>
+
+<li> <strong>YAML Metadata</strong> - Parse from markdown strings or files<br>
+<li> <strong>Shell Expansion</strong> - $VAR, ${VAR}, and $(command) substitution<br>
+<li> <strong>ERB Rendering</strong> - On-demand rendering with named parameters<br>
+<li> <strong>File Includes</strong> - Compose prompts from multiple files<br>
+<li> <strong>Custom Directives</strong> - Register custom methods for ERB templates<br>
+<li> <strong>Configurable Pipeline</strong> - Enable/disable stages per prompt or globally<br>
+<li> <strong>Comment Stripping</strong> - HTML comments removed before processing
+</td>
+</tr>
+</table>
+
+## Processing Pipeline
+
+Every prompt passes through four stages:
 
 ```mermaid
-graph TB
-    subgraph "Application Layer"
-        A[Your Application]
-        P[PromptManager::Prompt]
-    end
-    
-    subgraph "Processing Layer"
-        D[Directive Processor]
-        E[ERB Engine]
-        K[Keyword Substitution]
-    end
-    
-    subgraph "Storage Layer"
-        FS[FileSystem Adapter]
-        AR[ActiveRecord Adapter]
-        CA[Custom Adapter]
-    end
-    
-    A --> P
-    P --> D
-    P --> E
-    P --> K
-    P --> FS
-    P --> AR
-    P --> CA
-    
-    D --> |includes| FS
-    E --> |templates| P
-    K --> |substitutes| P
+graph LR
+    A[Strip HTML Comments] --> B[Extract YAML Metadata]
+    B --> C[Shell Expansion]
+    C --> D["ERB Rendering (on to_s)"]
 ```
 
-## Core Concepts
+1. **Strip HTML comments** -- `<!-- ... -->` removed before anything else
+2. **Extract YAML metadata** -- Front-matter between `---` fences parsed into `PM::Metadata`
+3. **Shell expansion** -- Environment variables and commands expanded (when `shell: true`)
+4. **ERB rendering** -- Templates evaluated on demand when `to_s` is called (when `erb: true`)
 
-### Parameterized Prompts
+## Quick Example
 
-Transform static prompts into dynamic templates:
+Given a file `review.md`:
 
-```ruby
-# Template with parameters
-prompt_text = "Translate '[TEXT]' from [SOURCE_LANG] to [TARGET_LANG]"
-
-# Filled with values
-prompt.parameters = {
-  "[TEXT]" => "Hello world",
-  "[SOURCE_LANG]" => "English", 
-  "[TARGET_LANG]" => "Spanish"
-}
+```markdown
+---
+title: Code Review
+parameters:
+  language: ruby
+  code: null
+---
+Review the following <%= language %> code:
 
-# Result: "Translate 'Hello world' from English to Spanish"
+<%= code %>
 ```
 
-### Directive Processing
-
-Use JCL-style directives for prompt composition:
-
-```text
-# Common header for all customer service prompts
-//include common/customer_service_header.txt
+Parse and render:
 
-# Dynamic template inclusion
-//include templates/[TEMPLATE_TYPE].txt
+```ruby
+require 'pm'
 
-Handle this customer inquiry about [TOPIC].
+parsed = PM.parse('review.md')
+puts parsed.metadata.title        #=> "Code Review"
+puts parsed.to_s('code' => source) #=> rendered prompt
 ```
 
-### Storage Adapters
-
-Choose your preferred storage backend:
-
-- **FileSystemAdapter**: Store prompts as text files
-- **ActiveRecordAdapter**: Store prompts in a database  
-- **Custom Adapters**: Build your own storage solution
-
-## Why PromptManager?
-
-### 🎯 **Organized Prompts**
-Keep your prompts organized in a structured, searchable format instead of scattered across your codebase.
-
-### 🔄 **Reusable Templates** 
-Create parameterized templates that can be reused across different contexts and applications.
-
-### 🛠️ **Powerful Processing**
-Advanced features like directive processing, ERB templating, and environment variable substitution.
-
-### 📈 **Scalable Architecture**
-Modular design supports everything from simple scripts to enterprise applications.
-
-### 🔍 **Easy Management**
-Built-in search capabilities and parameter history make prompt management effortless.
-
 ## Getting Started
 
-Ready to dive in? Here are some great places to start:
-
-<div class="grid cards" markdown>
-
--   :fontawesome-solid-rocket:{ .lg .middle } __Quick Start__
-
-    ---
-
-    Get PromptManager running in your project within minutes
-    
-    [:octicons-arrow-right-24: Quick Start](getting-started/quick-start.md)
-
--   :fontawesome-solid-book:{ .lg .middle } __Core Features__
-
-    ---
-
-    Learn about parameterized prompts, directives, and more
-    
-    [:octicons-arrow-right-24: Core Features](core-features/parameterized-prompts.md)
-
--   :fontawesome-solid-database:{ .lg .middle } __Storage Adapters__
-
-    ---
-
-    Choose the right storage solution for your needs
-    
-    [:octicons-arrow-right-24: Storage Options](storage/overview.md)
-
--   :fontawesome-solid-code:{ .lg .middle } __API Reference__
-
-    ---
-
-    Complete reference for all classes and methods
-    
-    [:octicons-arrow-right-24: API Docs](api/prompt-class.md)
-
-</div>
-
-## Community & Support
-
-- **GitHub**: [MadBomber/prompt_manager](https://github.com/MadBomber/prompt_manager)
-- **RubyGems**: [prompt_manager](https://rubygems.org/gems/prompt_manager)
-- **Issues**: [Report bugs or request features](https://github.com/MadBomber/prompt_manager/issues)
-- **Discussions**: [Community discussions](https://github.com/MadBomber/prompt_manager/discussions)
-
-## License
-
-PromptManager is released under the [MIT License](https://opensource.org/licenses/MIT).
+Head to [Installation](getting-started/installation.md) to add PM to your project, then follow the [Quick Start](getting-started/quick-start.md) guide.

data/lib/pm/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PM
+  class Configuration
+    attr_accessor :prompts_dir, :shell, :erb
+
+    def initialize
+      reset!
+    end
+
+    def reset!
+      @prompts_dir = ''
+      @shell       = true
+      @erb         = true
+    end
+  end
+end

data/lib/pm/directives.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PM
+  # --- Directive registry ---
+
+  @directives = {}
+
+  # 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.
+  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
+  end
+
+  # Returns the registered directives hash.
+  def self.directives
+    @directives
+  end
+
+  # Clears all directives and re-registers the built-ins.
+  def self.reset_directives!
+    @directives.clear
+    register_builtins
+  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/metadata.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'ostruct'
+
+module PM
+  # OpenStruct-based metadata with predicate methods for boolean keys.
+  class Metadata < OpenStruct
+    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
+      end
+    end
+  end
+end

data/lib/pm/parsed.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'ostruct'
+require 'erb'
+
+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]
+    end
+
+    # 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.
+    def to_s(values = {})
+      render_with(values, Set.new, 0)
+    end
+
+    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 })
+    end
+  end
+end

data/lib/pm/shell.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module PM
+  # Expands shell references in a string.
+  # $ENVAR and ${ENVAR} are replaced with the environment variable value.
+  # $(command) is executed and replaced with its stdout.
+  def self.expand_shell(string)
+    result = expand_commands(string)
+    expand_env_vars(result)
+  end
+
+  # Replaces $(command) with the command's stdout.
+  # Handles nested parentheses in commands.
+  def self.expand_commands(string)
+    result = string.dup
+    pos = 0
+
+    while (start = result.index(COMMAND_START, pos))
+      depth = 0
+      i = start + 1
+
+      while i < result.length
+        if result[i] == '('
+          depth += 1
+        elsif result[i] == ')'
+          depth -= 1
+          if depth == 0
+            command = result[(start + 2)...i]
+            output, status = Open3.capture2(command)
+            output = output.chomp
+            unless status.success?
+              raise "Shell command failed (exit #{status.exitstatus}): #{command}"
+            end
+            result[start..i] = output
+            pos = start + output.length
+            break
+          end
+        end
+        i += 1
+      end
+
+      break if depth != 0
+    end
+
+    result
+  end
+  private_class_method :expand_commands
+
+  # Replaces $ENVAR and ${ENVAR} with environment variable values.
+  # Missing variables are replaced with an empty string.
+  def self.expand_env_vars(string)
+    string.gsub(ENV_VAR_REGEXP) { ENV.fetch($1 || $2, '') }
+  end
+  private_class_method :expand_env_vars
+end

data/lib/pm/version.rb

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