prompt_manager 1.0.2 → 1.2.0

data/docs/guides/includes.md

@@ -1,184 +0,0 @@
-# Including Files
-
-The `include` directive lets you compose prompts from multiple files.
-
-## Basic Usage
-
-```markdown
----
-title: Full Review
-parameters:
-  code: null
----
-<%= include 'common/header.md' %>
-
-Review this code:
-<%= code %>
-
-<%= include 'common/footer.md' %>
-```
-
-```ruby
-parsed = PM.parse('full_review.md')
-puts parsed.to_s('code' => File.read('app.rb'))
-```
-
-## How Includes Work
-
-Each included file goes through the full processing pipeline:
-
-1. HTML comments stripped
-2. YAML metadata extracted
-3. Shell expansion applied
-4. ERB rendered (with the parent's parameter values)
-
-The included file's rendered content replaces the `<%= include ... %>` tag.
-
-## Path Resolution
-
-Include paths are resolved relative to the **parent file's directory**:
-
-```
-prompts/
-  review.md          # contains: <%= include 'common/header.md' %>
-  common/
-    header.md        # resolved from prompts/common/header.md
-```
-
-## Parameter Passing
-
-The parent's parameter values are passed to included files. Child files can use the same parameter names:
-
-```markdown
-<!-- parent.md -->
----
-parameters:
-  name: null
----
-<%= include 'greeting.md' %>
-Done.
-```
-
-```markdown
-<!-- greeting.md -->
----
-title: Greeting
----
-Hello, <%= name %>!
-```
-
-```ruby
-parsed = PM.parse('parent.md')
-parsed.to_s('name' => 'Alice')
-#=> "Hello, Alice!\nDone."
-```
-
-## Nested Includes
-
-Includes can be nested. File A can include File B, which includes File C:
-
-```markdown
-<!-- a.md -->
-<%= include 'b.md' %>
-
-<!-- b.md -->
-<%= include 'c.md' %>
-
-<!-- c.md -->
-Content from C
-```
-
-## Circular Include Detection
-
-PM detects circular includes and raises an error:
-
-```markdown
-<!-- circular_a.md -->
-<%= include 'circular_b.md' %>
-
-<!-- circular_b.md -->
-<%= include 'circular_a.md' %>
-```
-
-```ruby
-PM.parse('circular_a.md').to_s
-#=> RuntimeError: Circular include detected: /path/to/circular_a.md
-```
-
-## Includes Metadata
-
-After calling `to_s`, the parent's metadata has an `includes` key with a tree of what was included:
-
-```ruby
-parsed = PM.parse('full_review.md')
-parsed.to_s('code' => source)
-
-parsed.metadata.includes
-#=> [
-#     {
-#       path:     "/prompts/common/header.md",
-#       depth:    1,
-#       metadata: { title: "Header", ... },
-#       includes: []
-#     },
-#     {
-#       path:     "/prompts/common/footer.md",
-#       depth:    1,
-#       metadata: { title: "Footer", ... },
-#       includes: []
-#     }
-#   ]
-```
-
-Nested includes form a tree -- each entry's `includes` array contains its own children.
-
-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:
-
-```ruby
-PM.parse("---\n---\n<%= include 'other.md' %>").to_s
-#=> RuntimeError: include requires a file context (use PM.parse with a file path)
-```
-
-- When `erb: false`, the include directive does not execute and `metadata.includes` is an empty array.

data/docs/guides/index.md

@@ -1,11 +0,0 @@
-# Guides
-
-In-depth guides for each PM feature.
-
-- [Parsing Prompts](parsing.md) -- File paths vs raw strings, metadata extraction
-- [Parameters](parameters.md) -- Required and default parameters, rendering with `to_s`
-- [Shell Expansion](shell-expansion.md) -- Environment variables and command substitution
-- [ERB Rendering](erb-rendering.md) -- Template evaluation and disabling
-- [Including Files](includes.md) -- Composing prompts from multiple files
-- [Custom Directives](custom-directives.md) -- Registering your own ERB helpers
-- [Comment Stripping](comment-stripping.md) -- HTML comment removal

data/docs/guides/parameters.md

@@ -1,96 +0,0 @@
-# Parameters
-
-Parameters are declared in the YAML `parameters` hash and used as ERB template variables.
-
-## Declaring Parameters
-
-```markdown
----
-title: Code Review
-parameters:
-  language: ruby
-  code: null
-  style_guide: ~/guides/default.md
----
-Review the following <%= language %> code using the style guide
-at <%= style_guide %>:
-
-<%= code %>
-```
-
-## Required vs Default
-
-- **`null` value** -- the parameter is **required**. `to_s` raises `ArgumentError` if not provided.
-- **Any other value** -- used as the **default**. Can be overridden when calling `to_s`.
-
-```ruby
-parsed = PM.parse('code_review.md')
-
-parsed.metadata.parameters
-#=> {"language" => "ruby", "code" => nil, "style_guide" => "~/guides/default.md"}
-```
-
-## Rendering with to_s
-
-`to_s` accepts a Hash of parameter values:
-
-```ruby
-# Supply required params, accept defaults for the rest
-parsed.to_s('code' => File.read('app.rb'))
-
-# Override a default
-parsed.to_s('code' => File.read('app.py'), 'language' => 'python')
-```
-
-Symbol keys work too:
-
-```ruby
-parsed.to_s(code: File.read('app.rb'))
-```
-
-### All Defaults
-
-When every parameter has a default value, `to_s` needs no arguments:
-
-```ruby
-parsed.to_s  #=> renders with all defaults
-```
-
-### Missing Required Parameters
-
-Calling `to_s` without supplying a required parameter raises `ArgumentError`:
-
-```ruby
-parsed.to_s
-#=> ArgumentError: Missing required parameters: code
-```
-
-The error message lists all missing parameters.
-
-## Parameters in Included Files
-
-When a file includes another file via `<%= include 'child.md' %>`, the parent's parameter values are passed to the child. The child can use the same parameter names:
-
-```markdown
-<!-- parent.md -->
----
-title: Parent
-parameters:
-  name: null
----
-<%= include 'greeting.md' %>
-```
-
-```markdown
-<!-- greeting.md -->
----
-title: Greeting
----
-Hello, <%= name %>!
-```
-
-```ruby
-parsed = PM.parse('parent.md')
-parsed.to_s('name' => 'Alice')
-#=> "Hello, Alice!"
-```

data/docs/guides/parsing.md

@@ -1,151 +0,0 @@
-# Parsing Prompts
-
-`PM.parse` is the main entry point. It accepts a file path, a Symbol, a single word, or a raw string.
-
-## File Paths
-
-A source is treated as a file path when it:
-
-- Is a `Pathname` object
-- Responds to `to_path`
-- Is a String ending in `.md`
-- Is a Symbol (`.md` is appended, e.g. `:code_review` → `code_review.md`)
-- Is a single word containing only letters, digits, or underscores (`.md` is appended, e.g. `"code_review"` → `code_review.md`)
-
-```ruby
-# String file path
-parsed = PM.parse('code_review.md')
-
-# Pathname
-parsed = PM.parse(Pathname.new('code_review.md'))
-
-# Symbol (basename — .md appended)
-parsed = PM.parse(:code_review)
-
-# Single word (basename — .md appended)
-parsed = PM.parse('code_review')
-```
-
-When parsing a file, PM adds these keys to the metadata automatically:
-
-| Key | Type | Description |
-|-----|------|-------------|
-| `directory` | String | Absolute path to the file's parent directory |
-| `name` | String | Filename (e.g., `code_review.md`) |
-| `created_at` | Time | File creation timestamp |
-| `modified_at` | Time | Last modification timestamp |
-
-### prompts_dir
-
-Relative file paths are resolved against `PM.config.prompts_dir`:
-
-```ruby
-PM.configure { |c| c.prompts_dir = '~/.prompts' }
-
-PM.parse('agents/summarize.md')
-#=> reads ~/.prompts/agents/summarize.md
-```
-
-Absolute paths bypass `prompts_dir`:
-
-```ruby
-PM.parse('/etc/prompts/system.md')
-#=> reads /etc/prompts/system.md regardless of prompts_dir
-```
-
-## Raw Strings
-
-Any other string is parsed directly:
-
-```ruby
-parsed = PM.parse("---\ntitle: Hello\n---\nContent here")
-
-parsed.metadata.title  #=> "Hello"
-parsed.content         #=> "\nContent here\n"
-```
-
-String-parsed prompts do not have `directory`, `name`, `created_at`, or `modified_at` in their metadata.
-
-!!! 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:
-
-```markdown
----
-title: My Prompt
-provider: openai
-model: gpt-4
-temperature: 0.3
----
-The prompt content starts here.
-```
-
-All YAML keys become accessible via dot notation on the `PM::Metadata` object:
-
-```ruby
-parsed.metadata.title        #=> "My Prompt"
-parsed.metadata.provider     #=> "openai"
-parsed.metadata.temperature  #=> 0.3
-```
-
-Boolean keys also get predicate methods:
-
-```ruby
-parsed.metadata.shell   #=> true
-parsed.metadata.shell?  #=> true
-```
-
-### No Metadata
-
-Files without front-matter are valid. The metadata object is empty and the entire content is preserved:
-
-```ruby
-parsed = PM.parse("Just plain text")
-parsed.metadata.title  #=> nil
-parsed.content         #=> "Just plain text"
-```
-
-### Bracket Accessor
-
-You can also access metadata with bracket notation:
-
-```ruby
-parsed[:title]  #=> "My Prompt"
-```
-
-## Pipeline Stages
-
-After parsing, the content has been through these stages:
-
-1. HTML comments stripped
-2. YAML metadata extracted
-3. Shell expansion applied (if `shell: true`)
-
-ERB rendering happens later, on demand, when `to_s` is called.

data/docs/guides/shell-expansion.md

@@ -1,108 +0,0 @@
-# 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,70 +0,0 @@
-# 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 LR
-    A[Strip HTML Comments] --> B[Extract YAML Metadata]
-    B --> C[Shell Expansion]
-    C --> D["ERB Rendering (on to_s)"]
-```
-
-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`)
-
-## Quick Example
-
-Given a file `review.md`:
-
-```markdown
----
-title: Code Review
-parameters:
-  language: ruby
-  code: null
----
-Review the following <%= language %> code:
-
-<%= code %>
-```
-
-Parse and render:
-
-```ruby
-require 'pm'
-
-parsed = PM.parse('review.md')
-puts parsed.metadata.title        #=> "Code Review"
-puts parsed.to_s('code' => source) #=> rendered prompt
-```
-
-## Getting Started
-
-Head to [Installation](getting-started/installation.md) to add PM to your project, then follow the [Quick Start](getting-started/quick-start.md) guide.