prompt_manager 1.0.2 → 1.2.0

data/README.md

@@ -2,188 +2,128 @@
 
 <table>
 <tr>
-<td width="50%" align="center" valign="top">
-<img src="docs/assets/images/prompt_manager.gif" alt="PromptManager" width="70%"><br>
+<td width="40%" align="center" valign="top">
+<img src="docs/assets/images/prompt_manager.gif" alt="PromptManager" width="100%"><br>
 <em>"Prompts with superpowers"</em>
 </td>
-<td width="50%" valign="top">
-  Like an enchanted librarian enhancing books of knowledge, PromptManager (PM) helps you masterfully orchestrate and organize your AI prompts through wisdom and experience. Each prompt becomes a living entity that can be categorized, parameterized, and interconnected with golden threads of relationships. 
-
-  <h3>Key Features</h3>
-
-- <strong>YAML Metadata</strong> - Parse from markdown strings or files<br>
-- <strong>Conditional Shell Expansion</strong> - $ENVAR, ${ENVAR}, $(command) substitution<br>
-- <strong>Conditional ERB Templates</strong> - On-demand rendering with named parameters<br>
-- <strong>Recursive Include System</strong> - Compose prompts from multiple files<br>
-- <strong>Raw File Insert</strong> - Insert any file's content verbatim<br>
-- <strong>Custom Directives</strong> - Register custom methods for ERB templates<br>
-- <strong>Configurable Pipeline</strong> - Enable/disable stages per prompt or globally<br>
-- <strong>Comment Stripping</strong> - HTML comments removed before processing
+<td width="60%" valign="top">
+<strong>Parse YAML front matter from markdown, expand shell references, compose prompts from other files, and render ERB on demand.</strong><br><br>
+PM treats a prompt file as a parameterized template: YAML front matter for metadata and parameters, <code>$VAR</code> / <code>$(command)</code> for environment context, <code>&lt;%= ... %&gt;</code> for rendering, and <code>include</code> / <code>insert</code> for composition.
+
+<h3>Key Features</h3>
+<ul>
+<li><strong>YAML Metadata</strong> - Parse from markdown strings or files</li>
+<li><strong>Shell Expansion</strong> - <code>$VAR</code>, <code>${VAR}</code>, <code>$(command)</code>; <code>\$</code> escapes; code fences are skipped</li>
+<li><strong>ERB Templates</strong> - On-demand rendering with required and default parameters</li>
+<li><strong>Includes</strong> - Compose prompts from other files, with a tracked include tree</li>
+<li><strong>Raw Inserts</strong> - Drop any file in verbatim</li>
+<li><strong>Custom Directives</strong> - Blocks or <code>PM::Directive</code> subclasses, callable from ERB</li>
+<li><strong>Configurable Pipeline</strong> - Enable, disable, or lock stages globally or per file</li>
+<li><strong>Typed Errors</strong> - A <code>PM::Error</code> hierarchy for everything PM raises</li>
+<li><strong>Zero runtime dependencies</strong> - Ruby 4.0.9+ and its standard library</li>
+</ul>
 </td>
 </tr>
 </table>
 
-## Installation
-
-```ruby
-require 'pm'
-```
-
-## Configuration
+Full documentation: <https://madbomber.github.io/prompt_manager>
 
-Set global defaults with `PM.configure`:
-
-```ruby
-PM.configure do |config|
-  config.prompts_dir = '~/.prompts'   # default: ''
-  config.shell       = true           # default: true
-  config.erb         = true           # default: true
-end
-```
-
-**`prompts_dir`** is prepended to relative file paths passed to `PM.parse`. Absolute paths bypass it:
-
-```ruby
-PM.configure { |c| c.prompts_dir = '/usr/share/prompts' }
-
-PM.parse('code_review.md')
-#=> reads /usr/share/prompts/code_review.md
-
-PM.parse('/absolute/path/review.md')
-#=> reads /absolute/path/review.md (prompts_dir ignored)
-```
-
-**`shell`** and **`erb`** set the global defaults for new parses. Per-file YAML metadata overrides the global setting:
+## Installation
 
 ```ruby
-PM.configure { |c| c.shell = false }
-
-# All files now default to shell: false
-# A file with "shell: true" in its YAML still gets shell expansion
+# Gemfile
+gem 'prompt_manager'
 ```
 
-Reset all settings to defaults:
-
-```ruby
-PM.config.reset!
+```bash
+gem install prompt_manager
 ```
 
-Access the current configuration:
-
 ```ruby
-PM.config.prompts_dir  #=> ''
-PM.config.shell        #=> true
-PM.config.erb          #=> true
-```
-
-## Usage
-
-`PM.parse` accepts a file path, a Symbol, a single word, or a string:
-
-```ruby
-# File path (String ending in .md or Pathname)
-parsed = PM.parse('code_review.md')
-parsed = PM.parse(Pathname.new('code_review.md'))
-
-# Symbol or single word (treated as basename, .md appended)
-parsed = PM.parse(:code_review)    #=> parses code_review.md
-parsed = PM.parse('code_review')   #=> parses code_review.md
-
-# String content
-parsed = PM.parse("---\ntitle: Hello\n---\nContent here")
+require 'pm'
 ```
 
-When given a file path, `parse` adds `directory`, `name`, `created_at`, and `modified_at` to the metadata. Both forms run the full processing pipeline.
+Requires Ruby 4.0.9 or later. There are no runtime dependencies.
 
-Note that `PM.parse` treats single words (e.g. `'hello'`) as prompt IDs and appends `.md` to look them up as files. To parse a single word as literal string content, use `PM.parse_string`:
+## Quick start
 
-```ruby
-PM.parse('hello')              #=> looks for hello.md in prompts_dir
-PM.parse_string('hello')       #=> parses "hello" as string content
-PM.parse_string('Any string')  #=> always parsed as content, never as a file
-```
+Given `code_review.md`:
 
-Given a file `code_review.md`:
-
-```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 using the style guide
-at <%= style_guide %>:
+Review the following <%= language %> code:
 
 <%= code %>
 ```
 
-Parse it:
-
 ```ruby
 parsed = PM.parse('code_review.md')
-parsed.metadata.parameters
-#=> {'language' => 'ruby', 'code' => nil, 'style_guide' => '~/guides/default.md'}
-```
 
-Build the prompt with `to_s`:
+parsed.metadata.title       #=> "Code Review"
+parsed.metadata.model       #=> "gpt-4"
+parsed.parameters           #=> {"language" => "ruby", "code" => nil}
 
-```ruby
-# Provide required params, accept defaults for the rest
 parsed.to_s('code' => File.read('app.rb'))
-
-# Override defaults
 parsed.to_s('code' => File.read('app.py'), 'language' => 'python')
 
-# All params have defaults — no arguments needed
-parsed.to_s
-
-# Missing a required parameter raises an error
 parsed.to_s
-#=> ArgumentError: Missing required parameters: code
+#=> PM::MissingParameterError: Missing required parameters: code
 ```
 
-Parameters with a `null` default in the YAML are required. Parameters with any other default are optional.
+A parameter whose default is `null` is required. Any other default is optional.
 
-### Shell expansion
+## What `PM.parse` accepts
 
-Shell references are expanded during parsing (when `shell: true`, the default):
+```ruby
+PM.parse('code_review.md')             # String ending in .md  -> file
+PM.parse(Pathname.new('review.md'))    # Pathname              -> file
+PM.parse(:code_review)                 # Symbol                -> code_review.md
+PM.parse('code_review')                # single word           -> code_review.md
+PM.parse("---\ntitle: Hi\n---\nBody")  # anything else         -> string content
 
-```md
----
-title: Deploy Check
-parameters:
-  environment: null
----
-Current user: $USER
-Home directory: ${HOME}
-Date: $(date +%Y-%m-%d)
-Git branch: $(git rev-parse --abbrev-ref HEAD)
-Deploy to: <%= environment %>
+PM.parse_string('hello')               # always string content, never a file lookup
 ```
 
-- `$ENVAR` and `${ENVAR}` are replaced with the environment variable's value.
-- `$(command)` is executed and replaced with its stdout.
-- Missing environment variables are replaced with an empty string.
-- Failed commands raise an error.
+Relative paths are resolved against `PM.config.prompts_dir`. File parses add
+`directory`, `name`, `created_at`, and `modified_at` to the metadata.
 
-Shell expansion is also available directly:
+## Processing pipeline
 
-```ruby
-PM.expand_shell(string)
+1. **Strip HTML comments** (`<!-- ... -->`)
+2. **Extract YAML front matter** into `PM::Metadata`
+3. **Shell expansion** of the content, when `shell: true` (the default)
+4. **ERB rendering** when `to_s` is called, when `erb: true` (the default)
+
+Stages 3 and 4 can be turned off per file (`shell: false`, `erb: false`) or
+globally (`PM.config.shell = false`). `PM.config.lock!` makes the global values
+final so a file cannot turn a stage back on.
+
+## Shell expansion
+
+```markdown
+Current user: $USER
+Home: ${HOME}
+Date: $(date +%Y-%m-%d)
+Literal: \$HOME
 ```
 
-### Including other prompt files
+- `$VAR` and `${VAR}` (UPPERCASE names) are replaced with the environment value, or `""` when unset.
+- `$(command)` runs via the shell and is replaced with its stdout (trailing newline removed).
+- `\$` writes a literal `$`.
+- Command output is spliced in verbatim: a `$VAR` or `<%= %>` that a command prints is **not** expanded or evaluated.
+- Fenced code blocks (``` or ~~~) are copied through untouched.
+- A failing command raises `PM::ShellCommandError` (with `#command`, `#status`, `#stderr`); an unmatched `$(` raises `PM::ShellExpansionError`.
 
-Use `include` in ERB to compose prompts from multiple files:
+## Composing prompts
 
-```md
+```markdown
 ---
-title: Full Review
 parameters:
   code: null
 ---
@@ -192,182 +132,98 @@ parameters:
 Review this code:
 <%= code %>
 
-<%= include 'common/footer.md' %>
-```
-
-Included files go through the full processing pipeline (comment stripping, metadata extraction, shell expansion, ERB rendering). The parent's parameter values are passed to included files.
-
-Nested includes work — A can include B which includes C. Circular includes raise an error.
-
-### Inserting raw file content
-
-Use `insert` (or its alias `read`) to insert any file's content verbatim. Unlike `include`, the inserted content is not parsed, shell-expanded, or ERB-rendered — it appears as-is:
-
-```md
----
-title: Code Review
-parameters:
-  feedback_style: null
----
-Review this Ruby code:
-
-```ruby
 <%= insert 'app/models/user.rb' %>
 ```
 
-Use a <%= feedback_style %> tone.
-```
-
-Paths are resolved relative to the parent file's directory (same as `include`). Absolute paths work from any context. Missing files raise an error.
-
-`insert` vs `include`:
-
-| | `insert` | `include` |
+| | `include` | `insert` (alias `read`) |
 |---|---|---|
-| 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 |
+| Content is | parsed, shell-expanded, and ERB-rendered | copied verbatim |
+| Parameters | parent values passed down | n/a |
+| Nesting | yes, up to `PM.config.max_include_depth` (default 10) | none |
+| Same file twice | allowed; only a true cycle raises `PM::CircularIncludeError` | allowed |
+| Tracked in `metadata.includes` | yes | no |
 
-After calling `to_s`, the parent's metadata has an `includes` key with a tree of what was included:
+Paths resolve relative to the including file's directory. `include` needs a file
+context and raises `PM::IncludeContextError` from a string-parsed prompt.
 
-```ruby
-parsed = PM.parse('full_review.md')
-parsed.to_s('code' => File.read('app.rb'))
-
-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: []
-#     }
-#   ]
-```
-
-### Custom directives
-
-#### Block-based registration
-
-Register custom methods available in ERB templates:
+## Custom directives
 
 ```ruby
-PM.register(:env)  { |_ctx, key| ENV.fetch(key, '') }
-PM.register(:run)  { |_ctx, cmd| `#{cmd}`.chomp }
+PM.register(:env) { |_ctx, key| ENV.fetch(key, '') }
+PM.register(:webpage, :website, :web) { |_ctx, url| fetch_page(url) }   # aliases
 ```
 
-Register multiple names for the same directive (aliases):
-
-```ruby
-PM.register(:webpage, :website, :web) { |_ctx, url| fetch_page(url) }
-```
-
-#### 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, '')
+  desc "Recent commits"
+  def commits(ctx, count = 5)
+    `git log --oneline -#{count}`.chomp
   end
-
-  desc "Run a shell command"
-  def run(ctx, cmd)
-    `#{cmd}`.chomp
-  end
-  alias_method :exec, :run
+  alias_method :log, :commits
 end
 
-# Register all directive subclasses with PM
 PM::Directive.register_all
 ```
 
-`desc` marks the next method as a directive. Methods without `desc` are helpers and won't be registered. `alias_method` aliases are detected automatically.
+Every directive receives a `PM::RenderContext` (`directory`, `params`, `included`,
+`depth`, `metadata`) followed by the arguments from the ERB call. Registering a name
+that is already taken raises `PM::DirectiveAlreadyRegisteredError`; `PM.register`
+registers nothing if any requested name is taken. `PM.reset_directives!` restores
+the built-ins (`include`, `insert`, `read`).
+
+Inside a template a bare name resolves to a **parameter** when called without
+arguments, then to a **directive**, then to `nil`. Set
+`PM.config.strict_parameters = true` to make unknown names raise
+`PM::UnknownParameterError` instead.
 
-Override `build_dispatch_block` on your base class to customize how methods are called:
+## Configuration
 
 ```ruby
-class MyDirectives < PM::Directive
-  class << self
-    def build_dispatch_block(inst, method_name)
-      proc { |_ctx, *args| inst.send(method_name, args) }
-    end
-  end
+PM.configure do |c|
+  c.prompts_dir        = '~/.prompts'  # default ''
+  c.shell              = true          # default true
+  c.erb                = true          # default true
+  c.max_include_depth  = 10            # default 10; nil = unlimited
+  c.strict_parameters  = false         # default false
 end
-```
-
-#### RenderContext
-
-The first argument to every directive block (or class method) is a `PM::RenderContext`:
-
-- `ctx.directory` — directory of the file being rendered
-- `ctx.params` — merged parameter values
-- `ctx.metadata` — the current file's metadata
-- `ctx.depth` — include nesting depth
-- `ctx.included` — Set of file paths already in the include chain
 
-#### Duplicate detection and reset
-
-Registering a name that already exists raises an error:
-
-```ruby
-PM.register(:include) { |_ctx, path| path }
-#=> RuntimeError: Directive already registered: include
+PM.config.lock!     # per-file shell:/erb: can no longer override the globals
+PM.config.reset!    # back to defaults (also unlocks)
 ```
 
-Reset to built-in directives only:
+## Exporting
 
 ```ruby
-PM.reset_directives!
-# Restores: include, insert, read
+parsed.to_h          #=> { metadata: {...}, content: "..." }
+parsed.to_markdown   #=> front matter + content, re-parseable with PM.parse_string
 ```
 
-### Disabling processing stages
+## Errors
 
-Set `shell: false` or `erb: false` in the metadata to skip those stages:
+Everything PM raises itself descends from `PM::Error`, except parameter errors,
+which descend from `ArgumentError` for backward compatibility. Standard-library
+errors pass through: `Errno::ENOENT` for a missing file, `Psych::SyntaxError` for
+bad YAML, `SyntaxError` for bad ERB. See the
+[Errors reference](https://madbomber.github.io/prompt_manager/api/errors/).
 
-```md
----
-title: Raw Template
-shell: false
-erb: false
----
-This $USER and <%= name %> content is preserved as-is.
-```
+## Security model
 
-Both default to `true` when not specified. You can change these defaults globally via `PM.configure` (see [Configuration](#configuration)). Per-file metadata always overrides the global setting.
+Prompt files are **code**: ERB can run any Ruby, `$(...)` runs shell commands, and
+`include` / `insert` read any path the process can. Only parse files you trust.
+Command output and inserted file contents are inert (never expanded or evaluated),
+and `PM.config.lock!` keeps a file from re-enabling a stage you turned off. See the
+[Security guide](https://madbomber.github.io/prompt_manager/guides/security/).
 
-### HTML comment stripping
+PM is not thread-safe for configuration or directive registration; configure and
+register at boot, then parse and render from any thread.
 
-HTML comments are stripped before any other processing:
+## Development
 
-```md
-<!-- This comment will be removed -->
----
-title: My Prompt
----
-Content here. <!-- This too -->
-```
-
-Comments are also available directly:
-
-```ruby
-PM.strip_comments(string)
+```bash
+bundle install
+bundle exec rake test     # runs the suite with a 100% line-coverage gate
 ```
 
-## Processing pipeline
+## License
 
-1. Strip HTML comments
-2. Extract YAML metadata and markdown content
-3. Shell expansion (`$ENVAR`, `$(command)`) when `shell: true`
-4. ERB rendering on demand via `to_s` when `erb: true`
+MIT. See [LICENSE](LICENSE).

data/lib/pm/configuration.rb

@@ -1,17 +1,47 @@
 # frozen_string_literal: true
 
 module PM
+  # Global settings. Reach it through PM.config or PM.configure.
+  #
+  #   prompts_dir        -- prepended to relative paths given to PM.parse ('' = none)
+  #   shell              -- default for shell expansion when a file does not say
+  #   erb                -- default for ERB rendering when a file does not say
+  #   locked             -- when true, per-file `shell:` / `erb:` cannot override the globals
+  #   max_include_depth  -- deepest allowed `include` nesting (nil = unlimited)
+  #   strict_parameters  -- when true, an unknown name in a template raises instead of rendering ""
   class Configuration
-    attr_accessor :prompts_dir, :shell, :erb
+    attr_accessor :prompts_dir, :shell, :erb, :max_include_depth
+    attr_writer   :locked, :strict_parameters
+
+    DEFAULT_MAX_INCLUDE_DEPTH = 10
 
     def initialize
       reset!
     end
 
     def reset!
-      @prompts_dir = ''
-      @shell       = true
-      @erb         = true
+      @prompts_dir       = ''
+      @shell             = true
+      @erb               = true
+      @locked            = false
+      @max_include_depth = DEFAULT_MAX_INCLUDE_DEPTH
+      @strict_parameters = false
+      self
+    end
+
+    # Stop per-file front matter from overriding the global shell/erb settings.
+    def lock!
+      @locked = true
+      self
     end
+
+    def unlock!
+      @locked = false
+      self
+    end
+
+    def locked? = @locked
+
+    def strict_parameters? = @strict_parameters
   end
 end

data/lib/pm/core_directives.rb

@@ -1,31 +1,26 @@
 # frozen_string_literal: true
 
-# lib/pm/core_directives.rb
-#
-# PM's built-in directives: include, insert/read.
-# Defined as a PM::Directive subclass using the desc/alias DSL.
+require 'pathname'
 
 module PM
+  # PM's built-in directives: include, insert (alias read).
   class CoreDirectives < Directive
     desc "Include and render another prompt file"
     def include(ctx, path)
       unless ctx.directory
-        raise 'include requires a file context (use PM.parse with a file path)'
+        raise IncludeContextError, 'include requires a file context (use PM.parse with a file path)'
       end
 
       full_path = File.expand_path(path, ctx.directory)
+      check_include_allowed!(ctx, full_path)
 
-      if ctx.included.include?(full_path)
-        raise "Circular include detected: #{full_path}"
-      end
-
-      child  = PM.parse(full_path)
+      child  = PM.parse(Pathname.new(full_path)) # Pathname: always read as a file, whatever the extension
       result = child.render_with(ctx.params, ctx.included, ctx.depth + 1)
 
       ctx.metadata.includes << {
         path:     full_path,
         depth:    ctx.depth + 1,
-        metadata: child.metadata.to_h.reject { |k, _| k == :includes },
+        metadata: child.metadata.to_h.reject { |key, _| key == :includes },
         includes: child.metadata.includes
       }
 
@@ -34,18 +29,24 @@ module PM
 
     desc "Insert a file's raw content verbatim (no ERB, no shell expansion)"
     def insert(ctx, path)
-      full_path = if ctx&.directory
-                    File.expand_path(path, ctx.directory)
-                  else
-                    File.expand_path(path)
-                  end
-
-      unless File.exist?(full_path)
-        raise "insert: file not found: #{full_path}"
-      end
+      full_path = File.expand_path(path, ctx.directory)
+      raise FileNotFoundError, "insert: file not found: #{full_path}" unless File.file?(full_path)
 
       File.read(full_path)
     end
     alias_method :read, :insert
+
+    private
+
+    def check_include_allowed!(ctx, full_path)
+      if ctx.included.include?(full_path)
+        raise CircularIncludeError, "Circular include detected: #{full_path}"
+      end
+
+      max = PM.config.max_include_depth
+      return unless max && ctx.depth + 1 > max
+
+      raise IncludeDepthError, "Include depth exceeds #{max} (PM.config.max_include_depth): #{full_path}"
+    end
   end
 end