prompt_manager 1.0.2 → 1.2.0

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

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

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

@@ -1,7 +0,0 @@
-# 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,34 +0,0 @@
-# Installation
-
-## Gemfile
-
-Add PM to your Gemfile:
-
-```ruby
-gem 'prompt_manager'
-```
-
-Then run:
-
-```bash
-bundle install
-```
-
-## Manual Install
-
-```bash
-gem install prompt_manager
-```
-
-## Require
-
-```ruby
-require 'pm'
-```
-
-The `PM` module is the primary interface. All public methods are accessed through it.
-
-## Requirements
-
-- 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,94 +0,0 @@
-# Quick Start
-
-## Parse a String
-
-```ruby
-require 'pm'
-
-parsed = PM.parse("---\ntitle: Hello\n---\nContent here")
-
-parsed.metadata.title  #=> "Hello"
-parsed.content         #=> "\nContent here\n"
-```
-
-## Parse a File
-
-Given `greeting.md`:
-
-```markdown
----
-title: Greeting
-parameters:
-  name: null
----
-Hello, <%= name %>! Welcome.
-```
-
-```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
-
-parsed.metadata.title       #=> "Greeting"
-parsed.metadata.parameters  #=> {"name" => nil}
-
-# Render with parameters
-puts parsed.to_s('name' => 'Alice')
-#=> "Hello, Alice! Welcome."
-```
-
-When parsing a file, PM also adds `directory`, `name`, `created_at`, and `modified_at` to the metadata.
-
-## Parse a String Directly
-
-`PM.parse` treats single words as prompt IDs and looks them up as files. To always parse a string as content, use `PM.parse_string`:
-
-```ruby
-PM.parse('hello')              #=> looks for hello.md in prompts_dir
-PM.parse_string('hello')       #=> parses "hello" as string content
-
-parsed = PM.parse_string("---\ntitle: Inline\n---\nSome content")
-parsed.metadata.title  #=> "Inline"
-parsed.content         #=> "Some content\n"
-```
-
-## Parameters
-
-Parameters declared in the YAML front-matter define template variables:
-
-- **`null` value** -- parameter is required; `to_s` raises `ArgumentError` if missing
-- **Any other value** -- used as the default; can be overridden in `to_s`
-
-```ruby
-parsed = PM.parse("---\nparameters:\n  lang: ruby\n  code: null\n---\n<%= lang %>: <%= code %>")
-
-# Use defaults where available, supply required params
-parsed.to_s('code' => 'puts "hi"')  #=> "ruby: puts \"hi\""
-
-# Override defaults
-parsed.to_s('code' => 'print("hi")', 'lang' => 'python')
-```
-
-## Shell Expansion
-
-Environment variables and commands are expanded at parse time:
-
-```markdown
----
-title: Info
----
-User: $USER
-Date: $(date +%Y-%m-%d)
-```
-
-```ruby
-parsed = PM.parse('info.md')
-parsed.content  #=> "User: dewayne\nDate: 2025-01-15\n"
-```
-
-## Next Steps
-
-- [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

data/docs/guides/comment-stripping.md

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

@@ -1,180 +0,0 @@
-# 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 the built-in directives are registered: `include`, `insert`, and `read`.
-
-## 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" }
-```
-
-## Class-Based Directives
-
-For organized groups of directives, subclass `PM::Directive`:
-
-```ruby
-class MyDirectives < PM::Directive
-  desc "Fetch environment variable"
-  def env(ctx, key)
-    ENV.fetch(key, '')
-  end
-
-  desc "Run a shell command"
-  def run(ctx, cmd)
-    `#{cmd}`.chomp
-  end
-  alias_method :exec, :run
-
-  # No desc — not registered as a directive
-  def helper
-    "internal"
-  end
-end
-
-PM::Directive.register_all
-```
-
-`desc` marks the next method as a directive. Methods without `desc` are ordinary helpers and won't be registered. `alias_method` aliases are detected automatically via `UnboundMethod#original_name`.
-
-### Category name
-
-The class name determines a category heading (useful for help output):
-
-```ruby
-MyDirectives.category_name  #=> "My"
-PM::CoreDirectives.category_name  #=> "Core"
-```
-
-The last segment of the class name is used, with `Directives` stripped and camelCase split.
-
-### Dispatch customization
-
-Override `build_dispatch_block` to customize how methods are called when dispatched through `PM.directives`:
-
-```ruby
-class MyDirectives < PM::Directive
-  class << self
-    # Default: proc { |ctx, *args| inst.send(method_name, ctx, *args) }
-    def build_dispatch_block(inst, method_name)
-      proc { |_ctx, *args| inst.send(method_name, args.flatten) }
-    end
-  end
-end
-```
-
-### Subclass tracking
-
-All `PM::Directive` subclasses (direct and indirect) are tracked centrally:
-
-```ruby
-PM::Directive.directive_subclasses
-#=> [PM::CoreDirectives, MyDirectives, ...]
-```
-
-`register_all` iterates this list, creates a singleton instance per subclass, and registers each described method with `PM.register`.
-
-## Listing Directives
-
-```ruby
-PM.directives
-#=> { include: #<Proc>, insert: #<Proc>, read: #<Proc>, ... }
-```

data/docs/guides/erb-rendering.md

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