prompt_manager 0.5.8 → 1.0.0

data/docs/api/pm-module.md

@@ -0,0 +1,131 @@
+# PM Module
+
+The top-level `PM` module is the primary interface. All public methods are class methods on `PM`.
+
+## Parsing
+
+### PM.parse(source) → Parsed
+
+Parse a file or string and return a `PM::Parsed` object.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `source` | String, Symbol, Pathname | File path (`.md` extension or Pathname), Symbol, single word, or raw string |
+
+**Returns:** `PM::Parsed` (Struct with `metadata` and `content`)
+
+**Behavior:**
+
+- If `source` is a Symbol or a single word (letters, digits, underscores only), `.md` is appended and it is treated as a file basename
+- If `source` is a Pathname, responds to `to_path`, or is a String ending in `.md`, it is treated as a file path
+- File paths are resolved relative to `PM.config.prompts_dir` (unless absolute)
+- File parsing adds `directory`, `name`, `created_at`, `modified_at` to metadata
+- Processing pipeline: strip comments → extract YAML → shell expansion
+
+```ruby
+# File
+parsed = PM.parse('review.md')
+
+# Symbol or single word (basename — .md appended)
+parsed = PM.parse(:review)      #=> parses review.md
+parsed = PM.parse('review')     #=> parses review.md
+
+# String
+parsed = PM.parse("---\ntitle: Hello\n---\nContent")
+```
+
+---
+
+## Configuration
+
+### PM.config → Configuration
+
+Returns the singleton `PM::Configuration` instance.
+
+```ruby
+PM.config.prompts_dir  #=> ''
+PM.config.shell        #=> true
+```
+
+### PM.configure { |config| } → Configuration
+
+Yields the configuration instance for block-style configuration.
+
+```ruby
+PM.configure do |config|
+  config.prompts_dir = '~/.prompts'
+  config.shell = true
+  config.erb = true
+end
+```
+
+---
+
+## Utilities
+
+### PM.strip_comments(string) → String
+
+Remove all HTML comments (`<!-- ... -->`) from the string, including multiline.
+
+```ruby
+PM.strip_comments("Hello <!-- removed --> World")
+#=> "Hello  World"
+```
+
+### PM.expand_shell(string) → String
+
+Expand shell references in the string.
+
+- `$VAR` and `${VAR}` → environment variable value (empty string if unset)
+- `$(command)` → command stdout (trailing newline stripped)
+
+Only UPPERCASE variable names are expanded.
+
+```ruby
+PM.expand_shell("User: $USER, Date: $(date +%Y-%m-%d)")
+#=> "User: dewayne, Date: 2025-01-15"
+```
+
+**Raises:** `RuntimeError` if a command exits with non-zero status.
+
+---
+
+## Directives
+
+### PM.register(*names, &block) → nil
+
+Register one or more named directives available in ERB templates. Multiple names register the same block under each name (aliases).
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `*names` | Symbols, Strings | One or more directive names |
+| `block` | Proc | Receives `RenderContext` as first arg, then user args |
+
+**Raises:** `RuntimeError` if any name is already registered.
+
+```ruby
+PM.register(:env) { |_ctx, key| ENV.fetch(key, '') }
+PM.register(:webpage, :website, :web) { |_ctx, url| fetch_page(url) }
+```
+
+### PM.directives → Hash
+
+Returns the current directive registry.
+
+```ruby
+PM.directives
+#=> { include: #<Proc>, env: #<Proc> }
+```
+
+### PM.reset_directives! → nil
+
+Remove all custom directives and re-register only the built-in `include` directive.
+
+```ruby
+PM.reset_directives!
+PM.directives.keys  #=> [:include]
+```

data/docs/api/render-context.md

@@ -0,0 +1,51 @@
+# PM::RenderContext
+
+Context object passed as the first argument to every directive block during ERB rendering.
+
+## Source
+
+`lib/pm/parsed.rb`
+
+## Structure
+
+```ruby
+PM::RenderContext = Struct.new(:directory, :params, :included, :depth, :metadata)
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `directory` | String | Absolute path to the directory of the file being rendered |
+| `params` | Hash | Merged parameter values (defaults + overrides) |
+| `included` | Set | File paths already in the include chain (for circular detection) |
+| `depth` | Integer | Include nesting depth (0 for top-level file) |
+| `metadata` | PM::Metadata | Metadata of the file being rendered |
+
+## Usage in Directives
+
+Every directive block receives a RenderContext as its first argument:
+
+```ruby
+PM.register(:current_file) { |ctx| ctx.metadata.name || 'unknown' }
+
+PM.register(:nesting) { |ctx| ctx.depth.to_s }
+
+PM.register(:sibling) do |ctx, filename|
+  File.read(File.join(ctx.directory, filename))
+end
+
+PM.register(:param_dump) do |ctx|
+  ctx.params.map { |k, v| "#{k}: #{v}" }.join(', ')
+end
+```
+
+## Context During Includes
+
+When a file is included, the RenderContext reflects the included file's state:
+
+- `directory` is the included file's directory
+- `metadata` is the included file's metadata
+- `depth` increments by 1 for each nesting level
+- `included` contains all ancestor file paths
+- `params` carries the parent's merged parameter values

data/docs/architecture/design-decisions.md

@@ -0,0 +1,70 @@
+# Design Decisions
+
+Key architectural choices and their rationale.
+
+## OpenStruct for Metadata
+
+`PM::Metadata` extends `OpenStruct`, providing dynamic dot-notation access to any YAML key without predeclaring attributes.
+
+**Why:** Prompt metadata is inherently schemaless. Different prompts carry different keys (`provider`, `model`, `temperature`, `parameters`, custom keys). OpenStruct allows any key without configuration.
+
+**Trade-off:** Slightly slower than a fixed Struct for attribute access, but metadata objects are small and accessed infrequently relative to the parsing work.
+
+## ERB for Templates
+
+ERB was chosen as the template engine rather than Mustache, Liquid, or a custom syntax.
+
+**Why:**
+
+- Ships with Ruby's standard library -- no additional dependencies
+- Familiar to every Ruby developer
+- Full Ruby expressions available (not just variable substitution)
+- Custom directives integrate naturally as method calls
+
+**Trade-off:** ERB can execute arbitrary Ruby, which is more powerful than needed for simple variable substitution. PM mitigates this by encouraging the use of parameters and directives rather than inline Ruby logic.
+
+## Parse-Time vs Render-Time Split
+
+Shell expansion runs at parse time. ERB rendering runs on demand at `to_s` time.
+
+**Why:**
+
+- Shell references (`$USER`, `$(date)`) represent the environment at the time the prompt is loaded. They should reflect current state when the file is read.
+- ERB parameters represent per-invocation values that may change between calls. Deferring rendering allows the same parsed prompt to be rendered multiple times with different values.
+
+## Separate Shell and ERB Flags
+
+Both `shell` and `erb` can be independently enabled or disabled per file.
+
+**Why:** Some prompts are documentation templates that should show `$VAR` syntax literally. Others need shell expansion but contain ERB syntax meant for a different renderer. Independent flags give full control.
+
+## Include via ERB Directive
+
+File inclusion uses `<%= include 'path.md' %>` rather than a preprocessor directive or custom syntax.
+
+**Why:**
+
+- Consistent with the ERB rendering model -- includes are just another method call
+- Parameters flow naturally from parent to child
+- Custom directives use the same mechanism, so the system is uniform
+- No new syntax to learn
+
+**Trade-off:** Includes only work when ERB is enabled. Setting `erb: false` disables includes.
+
+## Circular Include Detection
+
+PM tracks included file paths in a Set passed through the render chain.
+
+**Why:** Circular includes would cause infinite recursion. The Set provides O(1) lookup and is threaded through the `RenderContext` without global state.
+
+## Configuration as Singleton
+
+`PM.config` returns a single `PM::Configuration` instance. Per-file metadata overrides it.
+
+**Why:** A global default makes sense for project-wide settings like `prompts_dir`. The override mechanism means individual files always have the final say, avoiding surprises.
+
+## UPPERCASE-Only Shell Variables
+
+Only `$UPPER_CASE` variable names are expanded by shell expansion. `$lowercase` is left as-is.
+
+**Why:** This avoids conflicts with ERB and other syntaxes that might use `$` followed by lowercase characters. Environment variables are conventionally uppercase, so this covers the practical use case without false matches.

data/docs/architecture/index.md

@@ -0,0 +1,6 @@
+# Architecture
+
+Technical details about PM's internal design.
+
+- [Processing Pipeline](processing-pipeline.md) -- The four-stage pipeline that transforms raw prompts
+- [Design Decisions](design-decisions.md) -- Rationale behind key architectural choices

data/docs/architecture/processing-pipeline.md

@@ -0,0 +1,112 @@
+# Processing Pipeline
+
+PM processes prompts through a four-stage pipeline. The first three stages run at parse time; the fourth runs on demand when `to_s` is called.
+
+## Overview
+
+```mermaid
+graph TD
+    A["Raw Input<br/>(file, symbol, word, or string)"] --> B["1. Strip HTML Comments"]
+    B --> C["2. Extract YAML Metadata"]
+    C --> D["3. Shell Expansion"]
+    D --> E["PM::Parsed<br/>(metadata + content)"]
+    E -->|"to_s(values)"| F["4. ERB Rendering"]
+    F --> G["Rendered String"]
+
+    style A fill:#00695c,color:#fff
+    style E fill:#00695c,color:#fff
+    style G fill:#f57f17,color:#000
+```
+
+## Stage 1: Strip HTML Comments
+
+**When:** Parse time
+**Method:** `PM.strip_comments`
+
+All `<!-- ... -->` comments are removed, including multiline spans. This runs first so comments don't interfere with metadata extraction.
+
+```
+Input:  "<!-- draft -->\n---\ntitle: Test\n---\nContent <!-- note -->"
+Output: "\n---\ntitle: Test\n---\nContent "
+```
+
+## Stage 2: Extract YAML Metadata
+
+**When:** Parse time
+**Regex:** `PM::METADATA_REGEXP`
+
+The `---`-delimited front-matter is parsed with `YAML.safe_load` into a Hash, then wrapped in a `PM::Metadata` object. Global defaults for `shell` and `erb` are applied if the file doesn't specify them.
+
+For file sources, `directory`, `name`, `created_at`, and `modified_at` are added from file stats.
+
+```
+Input:  "---\ntitle: Test\nshell: true\n---\nContent"
+Output: metadata = PM::Metadata(title: "Test", shell: true, erb: true)
+        content  = "Content"
+```
+
+## Stage 3: Shell Expansion
+
+**When:** Parse time (if `shell: true`)
+**Method:** `PM.expand_shell`
+
+Two sub-stages run in order:
+
+### 3a. Command Substitution
+
+`$(command)` sequences are found (with proper nesting of parentheses), executed, and replaced with stdout.
+
+### 3b. Environment Variables
+
+`$VAR` and `${VAR}` patterns (UPPERCASE only) are replaced with the corresponding environment variable value. Missing variables become empty strings.
+
+```
+Input:  "User: $USER\nDate: $(date +%Y-%m-%d)"
+Output: "User: dewayne\nDate: 2025-01-15"
+```
+
+## Stage 4: ERB Rendering
+
+**When:** On demand (`to_s` call, if `erb: true`)
+**Method:** `PM::Parsed#to_s`
+
+The content is evaluated as an ERB template. Parameter values (defaults merged with `to_s` arguments) and registered directives are available as local methods in the template.
+
+This stage also handles the `include` directive, which recursively parses and renders included files through the full pipeline.
+
+```
+Input:  "Hello, <%= name %>!"  (with params: {name: "Alice"})
+Output: "Hello, Alice!"
+```
+
+## Conditional Stages
+
+Stages 3 and 4 can be independently disabled:
+
+| Setting | Effect |
+|---------|--------|
+| `shell: false` | Stage 3 skipped; `$VAR` and `$(cmd)` preserved |
+| `erb: false` | Stage 4 skipped; `<%= ... %>` preserved |
+
+Settings can be per-file (YAML metadata) or global (`PM.configure`). Per-file always wins.
+
+## Data Flow
+
+```mermaid
+graph LR
+    subgraph "Parse Time"
+        A[Raw Text] --> B[No Comments]
+        B --> C[Metadata + Content]
+        C --> D[Shell-Expanded Content]
+    end
+
+    subgraph "Render Time"
+        D --> E[ERB Template]
+        E --> F[Final Output]
+    end
+
+    style A fill:#00695c,color:#fff
+    style F fill:#f57f17,color:#000
+```
+
+The `PM::Parsed` object returned by `PM.parse` holds the result of stages 1-3. Calling `to_s` triggers stage 4 and returns the final string.

data/docs/assets/css/custom.css

@@ -0,0 +1 @@
+/* PM (PromptManager) custom styles */

data/docs/examples/ai-agent-prompts.md

@@ -0,0 +1,173 @@
+# AI Agent Prompts
+
+Patterns for building and managing prompt libraries for AI agents.
+
+## Prompt Library Structure
+
+Organize prompts by agent role and task:
+
+```
+~/.prompts/
+  agents/
+    code_assistant/
+      system.md
+      review.md
+      refactor.md
+      explain.md
+    writer/
+      system.md
+      draft.md
+      edit.md
+    analyst/
+      system.md
+      summarize.md
+      compare.md
+  common/
+    output_json.md
+    output_markdown.md
+    safety.md
+```
+
+## Configuration
+
+```ruby
+PM.configure { |c| c.prompts_dir = '~/.prompts' }
+```
+
+## System Prompt Pattern
+
+`agents/code_assistant/system.md`:
+
+```markdown
+---
+title: Code Assistant System Prompt
+provider: anthropic
+model: claude-sonnet-4-20250514
+role: system
+---
+You are an expert software engineer. You help with code review,
+refactoring, and explanation.
+
+Current environment:
+- OS: $(uname -s)
+- User: $USER
+- Working directory: $(pwd)
+
+<%= include '../common/safety.md' %>
+```
+
+## Task Prompts with Parameters
+
+`agents/code_assistant/review.md`:
+
+```markdown
+---
+title: Code Review Task
+role: user
+parameters:
+  code: null
+  language: null
+  focus: general
+---
+<%= include '../common/output_markdown.md' %>
+
+Review the following <%= language %> code with a focus on <%= focus %>:
+
+```<%= language %>
+<%= code %>
+```
+```
+
+## Custom Directives for Agent Integration
+
+Register directives that fetch context dynamically:
+
+```ruby
+PM.register(:git_diff) do |_ctx|
+  `git diff --cached`.chomp
+end
+
+PM.register(:recent_commits) do |_ctx, count|
+  `git log --oneline -#{count}`.chomp
+end
+
+PM.register(:file_tree) do |ctx, path|
+  dir = path || ctx.directory
+  `find #{dir} -type f -name '*.rb' | head -20`.chomp
+end
+```
+
+Use them in prompts:
+
+```markdown
+---
+title: PR Review
+parameters:
+  focus: correctness
+---
+Review this PR with a focus on <%= focus %>.
+
+Changes:
+<%= git_diff %>
+
+Recent commit context:
+<%= recent_commits 5 %>
+
+Project structure:
+<%= file_tree nil %>
+```
+
+## Building a Prompt Runner
+
+```ruby
+require 'pm'
+
+PM.configure { |c| c.prompts_dir = '~/.prompts' }
+
+# Register project-specific directives
+PM.register(:git_diff) { |_ctx| `git diff --cached`.chomp }
+
+# Load and render
+system_prompt = PM.parse('agents/code_assistant/system.md')
+task_prompt   = PM.parse('agents/code_assistant/review.md')
+
+messages = [
+  { role: 'system', content: system_prompt.to_s },
+  { role: 'user',   content: task_prompt.to_s(
+    'code'     => File.read(ARGV[0]),
+    'language' => 'ruby',
+    'focus'    => 'security'
+  )}
+]
+
+# Use metadata for model configuration
+model = task_prompt.metadata.model || system_prompt.metadata.model
+```
+
+## Prompt Versioning
+
+Keep prompts in version control alongside your code. The metadata tracks useful context:
+
+```ruby
+parsed = PM.parse('agents/code_assistant/review.md')
+
+puts parsed.metadata.title        #=> "Code Review Task"
+puts parsed.metadata.modified_at  #=> 2025-01-15 10:30:00 -0500
+```
+
+Use `modified_at` for cache invalidation or audit logging.
+
+## Parameter Validation Pattern
+
+Check required parameters before rendering:
+
+```ruby
+parsed = PM.parse('agents/code_assistant/review.md')
+
+required = parsed.metadata.parameters
+  .select { |_k, v| v.nil? }
+  .keys
+
+puts "Required parameters: #{required.join(', ')}"
+#=> "Required parameters: code, language"
+```

data/docs/examples/code-review-prompt.md

@@ -0,0 +1,107 @@
+# Code Review Prompt
+
+A complete example of a parameterized code review prompt.
+
+## The Prompt File
+
+`prompts/code_review.md`:
+
+```markdown
+---
+title: Code Review
+provider: openai
+model: gpt-4
+temperature: 0.3
+parameters:
+  language: ruby
+  code: null
+  style_guide: ~/guides/default.md
+---
+Review the following <%= language %> code for:
+- Correctness
+- Performance
+- Readability
+- Security vulnerabilities
+
+Apply the coding standards from this style guide:
+<%= style_guide %>
+
+Code to review:
+
+<%= code %>
+```
+
+## Parsing
+
+```ruby
+require 'pm'
+
+PM.configure { |c| c.prompts_dir = './prompts' }
+
+parsed = PM.parse('code_review.md')
+```
+
+## Accessing Metadata
+
+```ruby
+parsed.metadata.title        #=> "Code Review"
+parsed.metadata.provider     #=> "openai"
+parsed.metadata.model        #=> "gpt-4"
+parsed.metadata.temperature  #=> 0.3
+
+parsed.metadata.parameters
+#=> {"language" => "ruby", "code" => nil, "style_guide" => "~/guides/default.md"}
+```
+
+Use metadata to configure your LLM client:
+
+```ruby
+client = OpenAI::Client.new
+response = client.chat(
+  parameters: {
+    model:       parsed.metadata.model,
+    temperature: parsed.metadata.temperature,
+    messages:    [{ role: 'user', content: prompt }]
+  }
+)
+```
+
+## Rendering
+
+```ruby
+# Minimal -- supply only the required parameter
+prompt = parsed.to_s('code' => File.read('app.rb'))
+
+# Override defaults
+prompt = parsed.to_s(
+  'code'        => File.read('main.py'),
+  'language'    => 'python',
+  'style_guide' => File.read('python_style.md')
+)
+```
+
+## Shell Expansion in Action
+
+The `style_guide` parameter defaults to `~/guides/default.md`. If shell expansion is enabled, the `~` is not expanded (it's not a shell variable). But you could use shell references elsewhere in the prompt:
+
+```markdown
+---
+title: Code Review with Context
+parameters:
+  code: null
+---
+Repository: $(basename $(git rev-parse --toplevel))
+Branch: $(git rev-parse --abbrev-ref HEAD)
+Reviewer: $USER
+
+Review this code:
+<%= code %>
+```
+
+After parsing, the shell references are already resolved:
+
+```ruby
+parsed = PM.parse('code_review_context.md')
+parsed.content
+#=> "Repository: my-project\nBranch: main\nReviewer: dewayne\n\nReview this code:\n<%= code %>\n"
+```

data/docs/examples/index.md

@@ -0,0 +1,7 @@
+# Examples
+
+Practical examples showing PM in real-world scenarios.
+
+- [Code Review Prompt](code-review-prompt.md) -- A complete code review prompt with parameters and shell context
+- [Multi-File Composition](multi-file-composition.md) -- Composing prompts from shared components with includes
+- [AI Agent Prompts](ai-agent-prompts.md) -- Patterns for building AI agent prompt libraries