prompt_manager 0.5.8 → 1.0.0

data/Rakefile

@@ -1,13 +1,5 @@
 # frozen_string_literal: true
 
-begin
-  require "tocer/rake/register"
-rescue LoadError => error
-  puts error.message
-end
-
-Tocer::Rake::Register.call
-
 require "bundler/gem_tasks"
 require "rake/testtask"
 

data/docs/api/configuration.md

@@ -1,355 +1,59 @@
-# Configuration API Reference
+# PM::Configuration
 
-PromptManager provides comprehensive configuration options to customize behavior for your specific needs.
+Global configuration for PM behavior. Accessed via `PM.config` or `PM.configure`.
 
-## Basic Configuration
+## Source
 
-```ruby
-PromptManager.configure do |config|
-  # Storage adapter (default: FileSystemAdapter)
-  config.storage = PromptManager::Storage::FileSystemAdapter.new
-  
-  # Default prompts directory (default: ~/prompts_dir/)
-  config.prompts_dir = '/path/to/your/prompts'
-  
-  # Enable debug logging (default: false)
-  config.debug = true
-  
-  # Custom logger (default: Rails.logger or Logger.new(STDOUT))
-  config.logger = Logger.new('/var/log/prompt_manager.log')
-end
-```
-
-## Configuration Options
-
-### Core Settings
-
-#### `storage`
-**Type:** `PromptManager::Storage::Base`
-**Default:** `FileSystemAdapter.new`
-
-The storage adapter to use for reading and writing prompts.
-
-```ruby
-# FileSystem storage
-config.storage = PromptManager::Storage::FileSystemAdapter.new(
-  prompts_dir: '/custom/prompts/path'
-)
-
-# ActiveRecord storage  
-config.storage = PromptManager::Storage::ActiveRecordAdapter.new(
-  model_class: Prompt
-)
-
-# Custom storage
-config.storage = MyCustomAdapter.new
-```
-
-#### `prompts_dir`
-**Type:** `String` or `Array<String>`
-**Default:** `File.join(Dir.home, 'prompts_dir')`
-
-Directory path(s) to search for prompt files when using FileSystemAdapter.
-
-```ruby
-# Single directory
-config.prompts_dir = '/app/prompts'
-
-# Multiple directories (search in order)
-config.prompts_dir = [
-  '/app/prompts',
-  '/shared/prompts', 
-  '/system/default_prompts'
-]
-```
-
-#### `debug`
-**Type:** `Boolean`
-**Default:** `false`
-
-Enable debug logging for troubleshooting.
-
-```ruby
-config.debug = true
-```
-
-#### `logger`
-**Type:** `Logger`
-**Default:** `Rails.logger` or `Logger.new(STDOUT)`
-
-Custom logger instance for PromptManager output.
-
-```ruby
-config.logger = Logger.new('/var/log/prompt_manager.log')
-config.logger.level = Logger::DEBUG
-```
-
-### Parameter Processing
+`lib/pm/configuration.rb`
 
-#### `save_parameter_history`
-**Type:** `Boolean`
-**Default:** `true`
+## Attributes
 
-Whether to save parameter values for reuse in future prompt renderings.
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prompts_dir` | String | `''` | Prepended to relative file paths in `PM.parse` |
+| `shell` | Boolean | `true` | Default shell expansion setting for new parses |
+| `erb` | Boolean | `true` | Default ERB rendering setting for new parses |
 
-```ruby
-config.save_parameter_history = false
-```
+All attributes have both getter and setter methods (`attr_accessor`).
 
-#### `parameter_history_file`
-**Type:** `String`
-**Default:** `~/.prompt_manager/parameters_history.yaml`
+## Methods
 
-File path for storing parameter history.
+### initialize
 
-```ruby
-config.parameter_history_file = '/app/data/prompt_history.yaml'
-```
+Creates a new Configuration with default values by calling `reset!`.
 
-#### `max_history_entries`
-**Type:** `Integer`
-**Default:** `10`
+### reset! → nil
 
-Maximum number of historical values to store per parameter.
+Restores all attributes to their defaults:
 
 ```ruby
-config.max_history_entries = 5
-```
-
-### ERB Processing
-
-#### `erb_timeout`
-**Type:** `Numeric`
-**Default:** `30` (seconds)
-
-Timeout for ERB template processing to prevent infinite loops.
+PM.config.reset!
 
-```ruby
-config.erb_timeout = 60  # 1 minute
+PM.config.prompts_dir  #=> ''
+PM.config.shell        #=> true
+PM.config.erb          #=> true
 ```
 
-#### `erb_safe_level`
-**Type:** `Integer`
-**Default:** `0`
-
-Ruby safe level for ERB evaluation (0-4, higher = more restrictive).
-
-```ruby
-config.erb_safe_level = 1  # Slightly more restrictive
-```
-
-### Directive Processing
-
-#### `max_include_depth`
-**Type:** `Integer`
-**Default:** `10`
+## Usage
 
-Maximum depth for nested `//include` directives to prevent circular includes.
+### Block Configuration
 
 ```ruby
-config.max_include_depth = 5
-```
-
-#### `directive_timeout`
-**Type:** `Numeric`
-**Default:** `30` (seconds)
-
-Timeout for directive processing.
-
-```ruby
-config.directive_timeout = 60
-```
-
-### Caching
-
-#### `cache_prompts`
-**Type:** `Boolean`
-**Default:** `false`
-
-Enable in-memory caching of prompt content.
-
-```ruby
-config.cache_prompts = true
-```
-
-#### `cache_ttl`
-**Type:** `Numeric`
-**Default:** `300` (5 minutes)
-
-Time-to-live for cached prompt content in seconds.
-
-```ruby
-config.cache_ttl = 600  # 10 minutes
-```
-
-#### `cache_store`
-**Type:** `ActiveSupport::Cache::Store`
-**Default:** `ActiveSupport::Cache::MemoryStore.new`
-
-Custom cache store for prompt content.
-
-```ruby
-config.cache_store = ActiveSupport::Cache::RedisStore.new(
-  url: ENV['REDIS_URL']
-)
-```
-
-### Error Handling
-
-#### `error_handler`
-**Type:** `Proc`
-**Default:** `nil`
-
-Custom error handler for prompt processing errors.
-
-```ruby
-config.error_handler = ->(error, context) {
-  Rails.logger.error "Prompt error: #{error.message}"
-  ErrorReporter.notify(error, context: context)
-  
-  # Return fallback content
-  "Service temporarily unavailable"
-}
-```
-
-#### `raise_on_missing_prompts`
-**Type:** `Boolean`
-**Default:** `true`
-
-Whether to raise exceptions for missing prompts or return nil.
-
-```ruby
-config.raise_on_missing_prompts = false
-```
-
-#### `raise_on_missing_parameters`
-**Type:** `Boolean`
-**Default:** `true`
-
-Whether to raise exceptions for missing parameters or substitute with placeholders.
-
-```ruby
-config.raise_on_missing_parameters = false
-```
-
-## Environment-based Configuration
-
-### Rails Configuration
-
-```ruby
-# config/environments/development.rb
-Rails.application.configure do
-  config.prompt_manager.debug = true
-  config.prompt_manager.prompts_dir = Rails.root.join('app', 'prompts')
-  config.prompt_manager.save_parameter_history = true
-end
-
-# config/environments/production.rb
-Rails.application.configure do
-  config.prompt_manager.debug = false
-  config.prompt_manager.cache_prompts = true
-  config.prompt_manager.cache_ttl = 3600  # 1 hour
-  
-  config.prompt_manager.error_handler = ->(error, context) {
-    Rollbar.error(error, context)
-    "Service temporarily unavailable"
-  }
-end
-```
-
-### Environment Variables
-
-PromptManager respects these environment variables:
-
-```bash
-# Storage configuration
-PROMPT_MANAGER_PROMPTS_DIR="/app/prompts"
-PROMPT_MANAGER_DEBUG="true"
-
-# Cache configuration  
-PROMPT_MANAGER_CACHE_PROMPTS="true"
-PROMPT_MANAGER_CACHE_TTL="600"
-
-# Database URL for ActiveRecord adapter
-DATABASE_URL="postgres://user:pass@localhost/prompts_db"
-```
-
-## Configuration Validation
-
-Validate your configuration:
-
-```ruby
-PromptManager.configure do |config|
-  config.storage = MyAdapter.new
-  config.debug = true
-end
-
-# Validate configuration
-begin
-  PromptManager.validate_configuration!
-  puts "Configuration valid"
-rescue PromptManager::ConfigurationError => e
-  puts "Configuration error: #{e.message}"
+PM.configure do |config|
+  config.prompts_dir = '~/.prompts'
+  config.shell = false
 end
 ```
 
-## Runtime Configuration
-
-Access current configuration:
+### Direct Access
 
 ```ruby
-# Get current storage adapter
-storage = PromptManager.configuration.storage
-
-# Check debug mode
-if PromptManager.configuration.debug
-  puts "Debug mode enabled"
-end
-
-# Access logger
-PromptManager.configuration.logger.info("Processing prompt...")
+PM.config.prompts_dir = '/usr/share/prompts'
+PM.config.erb = false
 ```
 
-## Configuration Best Practices
-
-### Development
-```ruby
-PromptManager.configure do |config|
-  config.debug = true
-  config.prompts_dir = './prompts'
-  config.save_parameter_history = true
-  config.cache_prompts = false  # Always reload for development
-end
-```
+## Override Behavior
 
-### Production
-```ruby
-PromptManager.configure do |config|
-  config.debug = false
-  config.cache_prompts = true
-  config.cache_ttl = 3600
-  
-  config.error_handler = ->(error, context) {
-    ErrorService.notify(error, context)
-    "Service temporarily unavailable"
-  }
-  
-  # Use database storage for high availability
-  config.storage = PromptManager::Storage::ActiveRecordAdapter.new
-end
-```
+Per-file YAML metadata always overrides the global setting. If a file has `shell: true` in its front-matter, shell expansion runs even when `PM.config.shell` is `false`.
 
-### Testing
-```ruby
-# spec/spec_helper.rb
-RSpec.configure do |config|
-  config.before(:each) do
-    PromptManager.configure do |config|
-      config.prompts_dir = Rails.root.join('spec', 'fixtures', 'prompts')
-      config.save_parameter_history = false
-      config.cache_prompts = false
-      config.raise_on_missing_prompts = true
-    end
-  end
-end
-```
+The global setting acts as the default when a file does not specify the value.

data/docs/api/constants.md

@@ -0,0 +1,60 @@
+# Constants
+
+Regular expressions and markers defined in the `PM` module.
+
+## Source
+
+`lib/pm.rb` and `lib/pm/shell.rb`
+
+## Reference
+
+### PM::VERSION
+
+```ruby
+PM::VERSION  #=> "1.0.0"
+```
+
+Current version of the PM library. Defined in `lib/pm/version.rb`.
+
+### PM::METADATA_REGEXP
+
+```ruby
+PM::METADATA_REGEXP
+```
+
+Matches YAML front-matter delimited by `---` fences. Captures the YAML content between the fences and the remaining body.
+
+Used internally by `PM.parse` to separate metadata from content.
+
+### PM::HTML_COMMENT_REGEXP
+
+```ruby
+PM::HTML_COMMENT_REGEXP
+```
+
+Matches HTML comments (`<!-- ... -->`), including multiline comments. Uses the `m` (multiline) flag for dot-matches-newline behavior.
+
+Used by `PM.strip_comments`.
+
+### PM::ENV_VAR_REGEXP
+
+```ruby
+PM::ENV_VAR_REGEXP
+```
+
+Matches environment variable references in two forms:
+
+- `${VAR}` -- braced form (captured in group 1)
+- `$VAR` -- bare form (captured in group 2)
+
+Only matches UPPERCASE variable names (`[A-Z_][A-Z0-9_]*`). Lowercase names are intentionally ignored to avoid conflicts with ERB and other syntax.
+
+Used by `PM.expand_shell` during the environment variable expansion phase.
+
+### PM::COMMAND_START
+
+```ruby
+PM::COMMAND_START  #=> "$("
+```
+
+String marker that identifies the start of a command substitution. Used by the shell expansion parser to find `$(command)` sequences with proper handling of nested parentheses.

data/docs/api/index.md

@@ -0,0 +1,14 @@
+# API Reference
+
+Complete reference for all PM classes, modules, and methods.
+
+## Classes and Modules
+
+| Name | Description |
+|------|-------------|
+| [PM Module](pm-module.md) | Top-level module with all public class methods |
+| [PM::Configuration](configuration.md) | Global settings (prompts_dir, shell, erb) |
+| [PM::Metadata](metadata.md) | OpenStruct-based metadata container |
+| [PM::Parsed](parsed.md) | Result object from `PM.parse` |
+| [PM::RenderContext](render-context.md) | Context passed to directive blocks |
+| [Constants](constants.md) | Regular expressions and markers |

data/docs/api/metadata.md

@@ -0,0 +1,99 @@
+# PM::Metadata
+
+OpenStruct-based metadata container with automatic predicate methods for boolean values.
+
+## Source
+
+`lib/pm/metadata.rb`
+
+## Inheritance
+
+```
+OpenStruct
+  └── PM::Metadata
+```
+
+## Constructor
+
+### Metadata.new(hash = {}) → Metadata
+
+Creates a new metadata object. All hash keys become accessible via dot notation. Boolean values also get predicate methods.
+
+```ruby
+meta = PM::Metadata.new(title: 'Hello', shell: true, erb: false)
+
+meta.title   #=> "Hello"
+meta.shell   #=> true
+meta.shell?  #=> true
+meta.erb     #=> false
+meta.erb?    #=> false
+```
+
+## Dot Notation Access
+
+All YAML keys from the front-matter are accessible as methods:
+
+```ruby
+parsed = PM.parse("---\ntitle: Test\nprovider: openai\nmodel: gpt-4\n---\nContent")
+
+parsed.metadata.title     #=> "Test"
+parsed.metadata.provider  #=> "openai"
+parsed.metadata.model     #=> "gpt-4"
+```
+
+## Predicate Methods
+
+Boolean keys (`true` or `false` values) automatically get a `?`-suffixed predicate method:
+
+```ruby
+meta = PM::Metadata.new(shell: true, verbose: false)
+
+meta.shell?    #=> true
+meta.verbose?  #=> false
+```
+
+Non-boolean keys do not get predicate methods:
+
+```ruby
+meta = PM::Metadata.new(title: 'Test')
+meta.respond_to?(:title?)  #=> false
+```
+
+## File-Specific Keys
+
+When `PM.parse` reads from a file, these keys are added automatically:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `directory` | String | Absolute path to the parent directory |
+| `name` | String | Filename (e.g., `review.md`) |
+| `created_at` | Time | File creation timestamp |
+| `modified_at` | Time | Last modification timestamp |
+
+## Special Keys
+
+### parameters
+
+The `parameters` hash from YAML front-matter:
+
+```ruby
+parsed.metadata.parameters
+#=> {"language" => "ruby", "code" => nil}
+```
+
+Keys with `nil` values are required parameters. Keys with any other value are defaults.
+
+### includes
+
+Populated after `to_s` is called. Contains a tree of included files:
+
+```ruby
+parsed.metadata.includes
+#=> [{ path: "/path/to/header.md", depth: 1, metadata: {...}, includes: [] }]
+```
+
+This is `nil` before `to_s` and is reset on each `to_s` call.
+
+### shell and erb
+
+Control processing behavior. Default to `true` when not specified in the YAML. The global configuration default is applied during metadata construction.

data/docs/api/parsed.md

@@ -0,0 +1,98 @@
+# PM::Parsed
+
+The result object returned by `PM.parse`. A Struct with two fields: `metadata` and `content`.
+
+## Source
+
+`lib/pm/parsed.rb`
+
+## Structure
+
+```ruby
+PM::Parsed = Struct.new(:metadata, :content)
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `metadata` | PM::Metadata | Parsed YAML front-matter |
+| `content` | String | Markdown content after metadata extraction and shell expansion |
+
+## Methods
+
+### `[](key)` → Object
+
+Bracket accessor that delegates to `metadata`:
+
+```ruby
+parsed = PM.parse("---\ntitle: Hello\n---\nContent")
+
+parsed[:title]    #=> "Hello"
+parsed['title']   #=> "Hello"
+```
+
+### to_s(values = {}) → String
+
+Render the prompt content with ERB template evaluation.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `values` | Hash | Parameter values to merge with defaults |
+
+**Returns:** Rendered prompt as String.
+
+**Raises:** `ArgumentError` if required parameters (those with `nil` defaults) are not provided.
+
+**Behavior:**
+
+1. Merges provided values with parameter defaults from metadata
+2. Validates all required parameters are present
+3. If `erb: true`, evaluates ERB with parameters and registered directives
+4. If `erb: false`, returns content as-is
+5. Populates `metadata.includes` with the include tree
+
+```ruby
+parsed = PM.parse('review.md')
+
+# With required params
+result = parsed.to_s('code' => File.read('app.rb'))
+
+# Override defaults
+result = parsed.to_s('code' => source, 'language' => 'python')
+
+# Symbol keys work
+result = parsed.to_s(code: source)
+```
+
+### render_with(values, included, depth) → String
+
+Internal method used by `to_s` and the `include` directive. Handles the ERB rendering pipeline with include tracking.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `values` | Hash | Merged parameter values |
+| `included` | Set | File paths already in the include chain |
+| `depth` | Integer | Current include nesting depth |
+
+This method is not typically called directly.
+
+## Typical Usage
+
+```ruby
+parsed = PM.parse('prompt.md')
+
+# Access metadata
+parsed.metadata.title
+parsed.metadata.parameters
+
+# Render
+output = parsed.to_s('key' => 'value')
+
+# Check includes after render
+parsed.metadata.includes
+```