prompt_manager 0.5.8 → 1.0.0

data/docs/guides/comment-stripping.md

@@ -0,0 +1,64 @@
+# Comment Stripping
+
+HTML comments are stripped before any other processing stage.
+
+## Automatic Stripping
+
+Comments are removed during `PM.parse`:
+
+```markdown
+<!-- This comment will be removed -->
+---
+title: My Prompt
+---
+Content here. <!-- This too -->
+```
+
+After parsing:
+
+```ruby
+parsed = PM.parse(source)
+parsed.content  #=> "\nContent here. \n"
+```
+
+## Multiline Comments
+
+Multiline comments are fully removed:
+
+```markdown
+<!--
+This entire block
+is removed
+-->
+---
+title: Example
+---
+Visible content.
+```
+
+## Comments Before Metadata
+
+Comments before the YAML front-matter are stripped first, so the metadata parser sees clean input:
+
+```markdown
+<!-- Editor note: draft version -->
+---
+title: My Prompt
+---
+Content
+```
+
+## Direct Access
+
+The comment stripping method is available as a standalone utility:
+
+```ruby
+PM.strip_comments("Hello <!-- removed --> World")
+#=> "Hello  World"
+```
+
+## Use Cases
+
+- **Editor notes** -- Leave comments for prompt authors that don't appear in the rendered output
+- **Disabled sections** -- Temporarily comment out parts of a prompt
+- **Documentation** -- Annotate prompt files without affecting the AI input

data/docs/guides/custom-directives.md

@@ -0,0 +1,115 @@
+# Custom Directives
+
+Register custom methods that become available inside ERB templates.
+
+## Registering a Directive
+
+```ruby
+PM.register(:read) { |_ctx, path| File.read(path) }
+PM.register(:env)  { |_ctx, key| ENV.fetch(key, '') }
+PM.register(:run)  { |_ctx, cmd| `#{cmd}`.chomp }
+```
+
+Use them in any prompt file:
+
+```markdown
+---
+title: Deploy Prompt
+---
+Hostname: <%= read '/etc/hostname' %>
+Environment: <%= env 'DEPLOY_ENV' %>
+Recent commits: <%= run 'git log --oneline -5' %>
+```
+
+## Aliases
+
+Register multiple names for the same directive by passing additional names:
+
+```ruby
+PM.register(:webpage, :website, :web) { |_ctx, url| fetch_page(url) }
+```
+
+All names point to the same block. Use any of them in ERB:
+
+```markdown
+<%= webpage 'https://example.com' %>
+<%= web 'https://example.com' %>
+```
+
+Duplicate detection still applies — if any name is already registered, an error is raised.
+
+## The RenderContext
+
+The first argument to every directive block is a `PM::RenderContext` with access to the current render state:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `directory` | String | Directory of the file being rendered |
+| `params` | Hash | Merged parameter values |
+| `metadata` | PM::Metadata | Current file's metadata |
+| `depth` | Integer | Include nesting depth (0 for top-level) |
+| `included` | Set | File paths already in the include chain |
+
+```ruby
+PM.register(:current_file) { |ctx| ctx.metadata.name || 'unknown' }
+PM.register(:nesting) { |ctx| ctx.depth.to_s }
+```
+
+The context is always the first argument. Additional arguments come from the ERB call:
+
+```ruby
+PM.register(:greet) { |_ctx, name| "Hello, #{name}!" }
+```
+
+```markdown
+<%= greet 'Alice' %>
+```
+
+## Duplicate Registration
+
+Registering a name that already exists raises an error:
+
+```ruby
+PM.register(:include) { |_ctx, path| path }
+#=> RuntimeError: Directive already registered: include
+```
+
+This protects built-in directives from being overwritten.
+
+## Resetting Directives
+
+Remove all custom directives and restore only the built-ins:
+
+```ruby
+PM.reset_directives!
+```
+
+After reset, only `include` is registered.
+
+## Directives in Included Files
+
+Custom directives are available in included files too. They share the same directive registry:
+
+```markdown
+<!-- parent.md -->
+<%= include 'child.md' %>
+
+<!-- child.md -->
+<%= read '/etc/hostname' %>
+```
+
+## Name Format
+
+Both symbols and strings are accepted:
+
+```ruby
+PM.register(:my_helper) { |_ctx| "works" }
+PM.register('other_helper') { |_ctx| "also works" }
+```
+
+## Listing Directives
+
+```ruby
+PM.directives
+#=> { include: #<Proc>, read: #<Proc>, ... }
+```

data/docs/guides/erb-rendering.md

@@ -0,0 +1,102 @@
+# ERB Rendering
+
+ERB templates are evaluated on demand when `to_s` is called.
+
+## Basics
+
+Any `<%= expression %>` in the content is evaluated as Ruby:
+
+```markdown
+---
+title: Math
+---
+Result: <%= 2 + 2 %>
+Today: <%= Time.now.strftime('%Y-%m-%d') %>
+```
+
+```ruby
+parsed = PM.parse('math.md')
+parsed.to_s  #=> "Result: 4\nToday: 2025-01-15\n"
+```
+
+## Template Parameters
+
+Parameters declared in the YAML front-matter are available as local methods inside ERB:
+
+```markdown
+---
+title: Greeting
+parameters:
+  name: World
+---
+Hello, <%= name %>!
+```
+
+```ruby
+parsed = PM.parse('greeting.md')
+parsed.to_s                    #=> "Hello, World!"
+parsed.to_s('name' => 'Alice') #=> "Hello, Alice!"
+```
+
+See [Parameters](parameters.md) for details on required vs default values.
+
+## Registered Directives
+
+Custom directives registered with `PM.register` are also available in ERB:
+
+```ruby
+PM.register(:upcase) { |_ctx, str| str.upcase }
+```
+
+```markdown
+---
+title: Example
+---
+<%= upcase 'hello' %>
+```
+
+See [Custom Directives](custom-directives.md) for the full guide.
+
+## Built-in Directives
+
+PM includes one built-in directive:
+
+- **`include`** -- Include and render another prompt file. See [Including Files](includes.md).
+
+## Disabling ERB
+
+Set `erb: false` in the file's YAML metadata:
+
+```markdown
+---
+title: Raw Template
+erb: false
+---
+This <%= expression %> is preserved as-is.
+```
+
+When ERB is disabled:
+
+- `to_s` returns the content without template evaluation
+- Parameters are ignored
+- The `include` directive does not execute
+- `metadata.includes` is an empty array after `to_s`
+
+### Global Default
+
+```ruby
+PM.configure { |c| c.erb = false }
+```
+
+Per-file metadata always overrides the global setting. A file with `erb: true` gets ERB rendering even when the global default is `false`.
+
+## Pipeline Position
+
+ERB rendering is the last stage of the pipeline, executed on demand:
+
+1. Strip HTML comments
+2. Extract YAML metadata
+3. Shell expansion (at parse time)
+4. **ERB rendering** (at `to_s` time)
+
+This means shell variables are already expanded before ERB sees the content. If content contains both `$VAR` and `<%= param %>`, the shell variable is resolved first, then ERB fills in the parameters.

data/docs/guides/includes.md

@@ -0,0 +1,146 @@
+# 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.
+
+## 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

@@ -0,0 +1,11 @@
+# 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

@@ -0,0 +1,96 @@
+# 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

@@ -0,0 +1,127 @@
+# 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.
+
+## 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.