prompt_manager 0.5.8 → 1.0.0

data/docs/examples/multi-file-composition.md

@@ -0,0 +1,123 @@
+# Multi-File Composition
+
+Compose prompts from shared components using the `include` directive.
+
+## Directory Structure
+
+```
+prompts/
+  review.md
+  common/
+    system_context.md
+    output_format.md
+    ruby_standards.md
+```
+
+## Shared Components
+
+`prompts/common/system_context.md`:
+
+```markdown
+---
+title: System Context
+---
+You are a senior software engineer with expertise in <%= language %>.
+Current date: $(date +%Y-%m-%d)
+User: $USER
+```
+
+`prompts/common/output_format.md`:
+
+```markdown
+---
+title: Output Format
+---
+Format your response as:
+1. Summary (2-3 sentences)
+2. Issues found (bulleted list)
+3. Suggestions (numbered list)
+4. Revised code (if applicable)
+```
+
+`prompts/common/ruby_standards.md`:
+
+```markdown
+---
+title: Ruby Standards
+---
+Follow these Ruby conventions:
+- Use snake_case for methods and variables
+- Prefer single-line blocks with braces for short expressions
+- Use guard clauses over nested conditionals
+- Avoid monkey-patching standard library classes
+```
+
+## The Composed Prompt
+
+`prompts/review.md`:
+
+```markdown
+---
+title: Full Code Review
+parameters:
+  language: ruby
+  code: null
+---
+<%= include 'common/system_context.md' %>
+
+<%= include 'common/ruby_standards.md' %>
+
+Review the following code:
+
+<%= code %>
+
+<%= include 'common/output_format.md' %>
+```
+
+## Usage
+
+```ruby
+PM.configure { |c| c.prompts_dir = './prompts' }
+
+parsed = PM.parse('review.md')
+prompt = parsed.to_s('code' => File.read('app.rb'))
+```
+
+The rendered prompt combines all four files into a single coherent prompt.
+
+## Inspecting the Include Tree
+
+```ruby
+parsed.metadata.includes
+#=> [
+#     { path: ".../common/system_context.md", depth: 1, metadata: {...}, includes: [] },
+#     { path: ".../common/ruby_standards.md", depth: 1, metadata: {...}, includes: [] },
+#     { path: ".../common/output_format.md",  depth: 1, metadata: {...}, includes: [] }
+#   ]
+```
+
+## Nested Includes
+
+Components can include other components. For example, `system_context.md` could include a `team_info.md`:
+
+```markdown
+---
+title: System Context
+---
+You are a senior software engineer.
+<%= include 'common/team_info.md' %>
+```
+
+The include tree reflects the nesting:
+
+```ruby
+parsed.metadata.includes[0][:includes]
+#=> [{ path: ".../common/team_info.md", depth: 2, metadata: {...}, includes: [] }]
+```
+
+## Benefits
+
+- **Reuse** -- Shared components (system context, output format) written once
+- **Consistency** -- Changes to a component propagate to all prompts that include it
+- **Modularity** -- Swap components per use case (different standards for different languages)
+- **Traceability** -- The includes tree shows exactly what went into each prompt

data/docs/getting-started/configuration.md

@@ -0,0 +1,106 @@
+# Configuration
+
+PM has three global settings controlled through `PM.configure`.
+
+## Setting Defaults
+
+```ruby
+PM.configure do |config|
+  config.prompts_dir = '~/.prompts'   # default: ''
+  config.shell       = true           # default: true
+  config.erb         = true           # default: true
+end
+```
+
+## prompts_dir
+
+Prepended to relative file paths passed to `PM.parse`. Absolute paths bypass it. Symbols and single words are converted to `.md` basenames first.
+
+```ruby
+PM.configure { |c| c.prompts_dir = '/usr/share/prompts' }
+
+PM.parse('code_review.md')
+#=> reads /usr/share/prompts/code_review.md
+
+PM.parse(:code_review)
+#=> reads /usr/share/prompts/code_review.md
+
+PM.parse('code_review')
+#=> reads /usr/share/prompts/code_review.md
+
+PM.parse('/absolute/path/review.md')
+#=> reads /absolute/path/review.md (prompts_dir ignored)
+```
+
+Subdirectories work naturally:
+
+```ruby
+PM.configure { |c| c.prompts_dir = '~/.prompts' }
+
+PM.parse('agents/summarize.md')
+#=> reads ~/.prompts/agents/summarize.md
+```
+
+## shell
+
+Controls whether shell expansion (`$VAR`, `$(command)`) runs during parsing. Defaults to `true`.
+
+```ruby
+PM.configure { |c| c.shell = false }
+
+# All files now skip shell expansion by default
+```
+
+Per-file YAML metadata overrides the global setting:
+
+```markdown
+---
+title: Override Example
+shell: true
+---
+This file gets shell expansion even when the global default is false.
+User: $USER
+```
+
+## erb
+
+Controls whether ERB rendering runs during `to_s`. Defaults to `true`.
+
+```ruby
+PM.configure { |c| c.erb = false }
+
+# All files now skip ERB rendering by default
+```
+
+Per-file metadata overrides this too:
+
+```markdown
+---
+title: Override Example
+erb: true
+---
+This file renders ERB even when the global default is false.
+Result: <%= 2 + 2 %>
+```
+
+## Resetting
+
+Restore all settings to their defaults:
+
+```ruby
+PM.config.reset!
+
+PM.config.prompts_dir  #=> ''
+PM.config.shell        #=> true
+PM.config.erb          #=> true
+```
+
+## Accessing Current Settings
+
+```ruby
+PM.config.prompts_dir
+PM.config.shell
+PM.config.erb
+```
+
+`PM.config` returns the singleton `PM::Configuration` instance. `PM.configure` yields the same instance.

data/docs/getting-started/index.md

@@ -0,0 +1,7 @@
+# Getting Started
+
+This section covers everything you need to start using PM in your Ruby projects.
+
+- [Installation](installation.md) -- Add PM to your project
+- [Quick Start](quick-start.md) -- Parse your first prompt in a few lines
+- [Configuration](configuration.md) -- Set global defaults for prompt directories, shell expansion, and ERB rendering

data/docs/getting-started/installation.md

@@ -1,97 +1,34 @@
 # Installation
 
-## System Requirements
+## Gemfile
 
-PromptManager requires:
-
-- **Ruby**: 2.7 or higher (3.0+ recommended)
-- **Operating System**: Linux, macOS, or Windows
-- **Dependencies**: No additional system dependencies required
-
-## Install the Gem
-
-### Using Bundler (Recommended)
-
-Add PromptManager to your project's `Gemfile`:
+Add PM to your Gemfile:
 
 ```ruby
-# Gemfile
 gem 'prompt_manager'
 ```
 
-Then install:
+Then run:
 
 ```bash
 bundle install
 ```
 
-### Using RubyGems
-
-Install directly with gem:
+## Manual Install
 
 ```bash
 gem install prompt_manager
 ```
 
-### Development Installation
-
-For development or to get the latest features:
-
-```bash
-git clone https://github.com/MadBomber/prompt_manager.git
-cd prompt_manager
-bundle install
-```
-
-## Verify Installation
-
-Test that PromptManager is installed correctly:
+## Require
 
 ```ruby
-require 'prompt_manager'
-puts PromptManager::VERSION
+require 'pm'
 ```
 
-## Dependencies
-
-PromptManager has minimal dependencies and automatically installs:
-
-- **No external system dependencies**
-- **Pure Ruby dependencies** only
-- **Lightweight footprint** for easy integration
-
-## Troubleshooting
-
-### Common Issues
-
-!!! warning "Ruby Version"
-    
-    If you see compatibility errors, ensure you're running Ruby 2.7+:
-    
-    ```bash
-    ruby --version
-    ```
-
-!!! tip "Bundler Issues"
-    
-    If bundle install fails, try updating bundler:
-    
-    ```bash
-    gem update bundler
-    bundle install
-    ```
-
-### Getting Help
-
-If you encounter installation issues:
-
-1. Check the [GitHub Issues](https://github.com/MadBomber/prompt_manager/issues)
-2. Search for similar problems in [Discussions](https://github.com/MadBomber/prompt_manager/discussions)  
-3. Create a new issue with:
-   - Ruby version (`ruby --version`)
-   - Gem version (`gem list prompt_manager`)
-   - Error message and full stack trace
+The `PM` module is the primary interface. All public methods are accessed through it.
 
-## Next Steps
+## Requirements
 
-Once installed, continue to the [Quick Start](quick-start.md) guide to begin using PromptManager.
+- Ruby >= 3.2.0
+- No runtime dependencies beyond the standard library (plus `ostruct` on Ruby 4.0+)

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

@@ -1,256 +1,81 @@
 # Quick Start
 
-This guide will get you up and running with PromptManager in just a few minutes.
+## Parse a String
 
-## 1. Install PromptManager
-
-```bash
-gem install prompt_manager
-```
-
-## 2. Set Up Your First Prompt
-
-Create a directory for your prompts and your first prompt file:
-
-```bash
-mkdir ~/.prompts
-```
-
-Create your first prompt file:
-
-=== "~/.prompts/greeting.txt"
-
-    ```text
-    # Description: A friendly greeting prompt
-    # Keywords: NAME, LANGUAGE
-    
-    Hello [NAME]! 
-    
-    I'm here to help you today. Please let me know how I can assist you,
-    and I'll respond in [LANGUAGE].
-    
-    What would you like to know about?
-    ```
-
-=== "~/.prompts/greeting.json"
-
-    ```json
-    {
-      "[NAME]": ["Alice", "Bob", "Charlie"],
-      "[LANGUAGE]": ["English", "Spanish", "French"]
-    }
-    ```
-
-## 3. Basic Usage
-
-Create a simple Ruby script to use your prompt:
-
-```ruby title="quick_example.rb"
-#!/usr/bin/env ruby
-
-require 'prompt_manager'
-
-# Configure the FileSystem storage adapter
-PromptManager::Prompt.storage_adapter = 
-  PromptManager::Storage::FileSystemAdapter.config do |config|
-    config.prompts_dir = File.expand_path('~/.prompts')
-  end.new
-
-# Load your prompt
-prompt = PromptManager::Prompt.new(id: 'greeting')
-
-# Set parameter values
-prompt.parameters = {
-  "[NAME]" => "Alice",
-  "[LANGUAGE]" => "English"
-}
-
-# Generate the final prompt text
-puts "=== Generated Prompt ==="
-puts prompt.to_s
-
-# Save any parameter changes
-prompt.save
-```
+```ruby
+require 'pm'
 
-Run it:
+parsed = PM.parse("---\ntitle: Hello\n---\nContent here")
 
-```bash
-ruby quick_example.rb
+parsed.metadata.title  #=> "Hello"
+parsed.content         #=> "\nContent here\n"
 ```
 
-Expected output:
-```
-=== Generated Prompt ===
-Hello Alice! 
+## Parse a File
 
-I'm here to help you today. Please let me know how I can assist you,
-and I'll respond in English.
+Given `greeting.md`:
 
-What would you like to know about?
+```markdown
+---
+title: Greeting
+parameters:
+  name: null
+---
+Hello, <%= name %>! Welcome.
 ```
 
-## 4. Understanding the Workflow
+```ruby
+# Any of these forms work:
+parsed = PM.parse('greeting.md')    # explicit .md extension
+parsed = PM.parse(:greeting)        # Symbol — .md appended
+parsed = PM.parse('greeting')       # single word — .md appended
 
-The basic PromptManager workflow involves:
+parsed.metadata.title       #=> "Greeting"
+parsed.metadata.parameters  #=> {"name" => nil}
 
-```mermaid
-graph LR
-    A[Create Prompt File] --> B[Configure Storage]
-    B --> C[Load Prompt]
-    C --> D[Set Parameters]
-    D --> E[Generate Text]
-    E --> F[Save Changes]
+# Render with parameters
+puts parsed.to_s('name' => 'Alice')
+#=> "Hello, Alice! Welcome."
 ```
 
-### Step by Step:
-
-1. **Create Prompt File**: Write your template with `[KEYWORDS]`
-2. **Configure Storage**: Choose FileSystem or ActiveRecord adapter
-3. **Load Prompt**: Create a Prompt instance with an ID
-4. **Set Parameters**: Provide values for your keywords
-5. **Generate Text**: Call `to_s` to get the final prompt
-6. **Save Changes**: Persist parameter updates
+When parsing a file, PM also adds `directory`, `name`, `created_at`, and `modified_at` to the metadata.
 
-## 5. Advanced Quick Start
+## Parameters
 
-Here's a more advanced example showing multiple features:
+Parameters declared in the YAML front-matter define template variables:
 
-```ruby title="advanced_example.rb"
-require 'prompt_manager'
+- **`null` value** -- parameter is required; `to_s` raises `ArgumentError` if missing
+- **Any other value** -- used as the default; can be overridden in `to_s`
 
-# Configure storage
-PromptManager::Prompt.storage_adapter = 
-  PromptManager::Storage::FileSystemAdapter.config do |config|
-    config.prompts_dir = File.expand_path('~/.prompts')
-  end.new
-
-# Create a prompt with directives and ERB
-prompt = PromptManager::Prompt.new(
-  id: 'advanced_greeting',
-  erb_flag: true,
-  envar_flag: true
-)
-
-# Set parameters
-prompt.parameters = {
-  "[USER_NAME]" => "Alice",
-  "[TASK_TYPE]" => "translation",
-  "[URGENCY]" => "high"
-}
-
-# Display available keywords
-puts "Available keywords: #{prompt.keywords.join(', ')}"
+```ruby
+parsed = PM.parse("---\nparameters:\n  lang: ruby\n  code: null\n---\n<%= lang %>: <%= code %>")
 
-# Generate and display the result
-puts "\n=== Final Prompt ==="
-puts prompt.to_s
+# Use defaults where available, supply required params
+parsed.to_s('code' => 'puts "hi"')  #=> "ruby: puts \"hi\""
 
-# Save changes
-prompt.save
-puts "\nPrompt saved successfully!"
+# Override defaults
+parsed.to_s('code' => 'print("hi")', 'lang' => 'python')
 ```
 
-=== "~/.prompts/advanced_greeting.txt"
-
-    ```text
-    # Advanced greeting with directives and ERB
-    //include common/header.txt
-    
-    Dear [USER_NAME],
-    
-    <% if '[URGENCY]' == 'high' %>
-    🚨 URGENT: This [TASK_TYPE] request requires immediate attention.
-    <% else %>
-    📋 Standard [TASK_TYPE] request for processing.
-    <% end %>
-    
-    Current system time: <%= Time.now.strftime('%Y-%m-%d %H:%M:%S') %>
-    Working directory: <%= Dir.pwd %>
-    
-    __END__
-    This section is ignored - useful for notes and documentation.
-    ```
-
-## 6. Next Steps
-
-Now that you have PromptManager working, explore these areas:
-
-### Learn Core Features
-- [Parameterized Prompts](../core-features/parameterized-prompts.md) - Master keyword substitution
-- [Directive Processing](../core-features/directive-processing.md) - Include files and process commands
-- [ERB Integration](../core-features/erb-integration.md) - Dynamic templating
-
-### Storage Options  
-- [FileSystem Adapter](../storage/filesystem-adapter.md) - File-based storage
-- [ActiveRecord Adapter](../storage/activerecord-adapter.md) - Database storage
-- [Custom Adapters](../storage/custom-adapters.md) - Build your own
-
-### Advanced Usage
-- [Custom Keywords](../advanced/custom-keywords.md) - Define your own keyword patterns
-- [Search Integration](../advanced/search-integration.md) - Find prompts quickly
-- [Performance Tips](../advanced/performance.md) - Optimize for large collections
-
-### Real Examples
-- [Basic Examples](../examples/basic.md) - Simple use cases
-- [Advanced Examples](../examples/advanced.md) - Complex scenarios
-- [Real World Cases](../examples/real-world.md) - Production examples
-
-## Common Patterns
+## Shell Expansion
 
-Here are some common patterns you'll use frequently:
+Environment variables and commands are expanded at parse time:
 
-### Parameter History
-```ruby
-# Access parameter history (since v0.3.0)
-prompt.parameters["[NAME]"]  # Returns ["Alice", "Bob", "Charlie"] 
-latest_name = prompt.parameters["[NAME]"].last  # "Charlie"
-```
-
-### Error Handling
-```ruby
-begin
-  prompt = PromptManager::Prompt.new(id: 'missing')
-rescue PromptManager::StorageError => e
-  puts "Storage error: #{e.message}"
-rescue PromptManager::ParameterError => e
-  puts "Parameter error: #{e.message}"
-end
+```markdown
+---
+title: Info
+---
+User: $USER
+Date: $(date +%Y-%m-%d)
 ```
 
-### Search and Discovery
 ```ruby
-# List all available prompts
-prompts = PromptManager::Prompt.list
-puts "Available prompts: #{prompts.join(', ')}"
-
-# Search for prompts (requires search_proc configuration)
-results = PromptManager::Prompt.search('greeting')
+parsed = PM.parse('info.md')
+parsed.content  #=> "User: dewayne\nDate: 2025-01-15\n"
 ```
 
-## Troubleshooting
-
-### File Not Found
-If you get "file not found" errors, check:
-
-1. **Prompt directory exists**: `ls ~/.prompts`
-2. **File has correct extension**: Should be `.txt` by default
-3. **Prompt ID matches filename**: `greeting` looks for `greeting.txt`
-
-### Parameter Errors
-If parameters aren't substituting:
-
-1. **Check keyword format**: Must be `[UPPERCASE]` by default
-2. **Verify parameter keys match**: Case-sensitive matching
-3. **Ensure parameters are set**: Call `prompt.parameters = {...}`
-
-### Permission Issues
-If you can't write to the prompts directory:
-
-```bash
-chmod 755 ~/.prompts
-chmod 644 ~/.prompts/*.txt
-chmod 644 ~/.prompts/*.json
-```
+## Next Steps
 
-Need help? Check our [testing guide](../development/testing.md) or [open an issue](https://github.com/MadBomber/prompt_manager/issues).
+- [Configuration](configuration.md) -- Set a prompts directory and global defaults
+- [Parsing Guide](../guides/parsing.md) -- File vs string parsing in depth
+- [Parameters Guide](../guides/parameters.md) -- Required and default parameters