prompt_manager 1.0.2 → 1.2.0

data/lib/pm/shell.rb

@@ -1,57 +1,112 @@
 # frozen_string_literal: true
 
 require 'open3'
+require 'strscan'
 
 module PM
-  # Expands shell references in a string.
-  # $ENVAR and ${ENVAR} are replaced with the environment variable value.
-  # $(command) is executed and replaced with its stdout.
-  def self.expand_shell(string)
-    result = expand_commands(string)
-    expand_env_vars(result)
+  # Expands shell references in a string in a single left-to-right pass:
+  #
+  #   $(command)  -- replaced with the command's stdout (trailing newline removed)
+  #   $VAR, ${VAR} -- replaced with the environment variable (UPPERCASE names only; "" if unset)
+  #   \$          -- a literal dollar sign; the backslash is removed
+  #
+  # Command output is spliced in verbatim and never re-scanned, so a `$VAR` or
+  # `$(...)` that a command prints stays literal. With `erb_safe: true` any
+  # `<%` in command output is written as `<%%`, which ERB renders as a literal
+  # `<%`, so output cannot inject Ruby into a later ERB pass.
+  #
+  # Fenced code blocks (lines starting with ``` or ~~~) are copied through
+  # untouched: a prompt can show shell syntax to the model without running it.
+  #
+  # Raises PM::ShellExpansionError for an unmatched `$(` and
+  # PM::ShellCommandError when a command exits non-zero.
+  def self.expand_shell(string, erb_safe: false)
+    ShellExpander.new(string, erb_safe: erb_safe).expand
   end
 
-  # Replaces $(command) with the command's stdout.
-  # Handles nested parentheses in commands.
-  def self.expand_commands(string)
-    result = string.dup
-    pos = 0
+  class ShellExpander
+    FENCE_OPEN_REGEXP  = /[ ]{0,3}(`{3,}|~{3,})[^\n]*(?:\n|\z)/
+    LINE_REGEXP        = /[^\n]*(?:\n|\z)/
+    ESCAPED_DOLLAR     = /\\\$/
+    COMMAND_OPEN       = /\$\(/
 
-    while (start = result.index(COMMAND_START, pos))
-      depth = 0
-      i = start + 1
+    def initialize(string, erb_safe: false)
+      @scanner  = StringScanner.new(string)
+      @erb_safe = erb_safe
+    end
 
-      while i < result.length
-        if result[i] == '('
-          depth += 1
-        elsif result[i] == ')'
-          depth -= 1
-          if depth == 0
-            command = result[(start + 2)...i]
-            output, status = Open3.capture2(command)
-            output = output.chomp
-            unless status.success?
-              raise "Shell command failed (exit #{status.exitstatus}): #{command}"
-            end
-            result[start..i] = output
-            pos = start + output.length
-            break
-          end
+    def expand
+      out = +''
+      at_line_start = true
+
+      until @scanner.eos?
+        if at_line_start && (fence = @scanner.scan(FENCE_OPEN_REGEXP))
+          out << fence << copy_fenced_block(fence)
+        elsif @scanner.scan(ESCAPED_DOLLAR)
+          out << '$'
+        elsif @scanner.scan(COMMAND_OPEN)
+          out << run_command
+        elsif @scanner.scan(ENV_VAR_REGEXP)
+          out << ENV.fetch(@scanner[1] || @scanner[2], '')
+        else
+          out << @scanner.getch
         end
-        i += 1
+
+        at_line_start = out.end_with?("\n")
       end
 
-      break if depth != 0
+      out
     end
 
-    result
-  end
-  private_class_method :expand_commands
+    private
+
+    # Copies lines verbatim up to and including the closing fence (or end of input).
+    def copy_fenced_block(open_line)
+      marker = open_line[/`{3,}|~{3,}/]
+      close  = /\A[ ]{0,3}#{Regexp.escape(marker[0])}{#{marker.length},}[ \t]*(?:\n|\z)\z/
+      out    = +''
+
+      until @scanner.eos?
+        line = @scanner.scan(LINE_REGEXP)
+        out << line
+        break if line.match?(close)
+      end
+
+      out
+    end
+
+    # Called with the scanner positioned just after "$(". Finds the matching
+    # ")" (honouring nested parentheses), runs the command, and returns its stdout.
+    def run_command
+      command = read_command
+      output, stderr, status = Open3.capture3(command)
 
-  # Replaces $ENVAR and ${ENVAR} with environment variable values.
-  # Missing variables are replaced with an empty string.
-  def self.expand_env_vars(string)
-    string.gsub(ENV_VAR_REGEXP) { ENV.fetch($1 || $2, '') }
+      raise ShellCommandError.new(command, status, stderr) unless status.success?
+
+      $stderr.write(stderr) unless stderr.empty? # keep warnings visible, as with 1.0.x
+      output = output.chomp
+      output = output.gsub('<%', '<%%') if @erb_safe
+      output
+    end
+
+    def read_command
+      depth   = 1
+      command = +''
+
+      until @scanner.eos?
+        char = @scanner.getch
+        if char == '('
+          depth += 1
+        elsif char == ')'
+          depth -= 1
+          break if depth.zero?
+        end
+        command << char
+      end
+
+      raise ShellExpansionError, "Unmatched $( in shell expansion: $(#{command}" unless depth.zero?
+
+      command
+    end
   end
-  private_class_method :expand_env_vars
 end

data/lib/pm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PM
-  VERSION = '1.0.2'
+  VERSION = '1.2.0'
 end

data/lib/pm.rb

@@ -4,8 +4,11 @@ require 'date'
 require 'pathname'
 require 'yaml'
 
-# PM (PromptManager) parses YAML metadata from markdown strings or files.
-# Processing pipeline: strip HTML comments → extract metadata → shell expansion → ERB on demand.
+# PM (PromptManager) parses YAML front matter from markdown strings or files.
+# Pipeline: strip HTML comments → extract metadata → shell expansion → ERB on demand (#to_s).
+#
+# Not thread-safe: PM.config and the directive registry are process-wide state.
+# Configure and register directives at boot, then parse and render from any thread.
 module PM
   METADATA_REGEXP = /
     \A
@@ -19,8 +22,13 @@ module PM
   /mx
 
   HTML_COMMENT_REGEXP = /<!--.*?-->/m
-  ENV_VAR_REGEXP     = /\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/
-  COMMAND_START      = '$('
+  ENV_VAR_REGEXP      = /\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/
+  COMMAND_START       = '$('
+
+  # Front-matter keys that control the pipeline and must be true/false.
+  FLAG_KEYS   = %w[shell erb].freeze
+  TRUE_WORDS  = %w[true yes on].freeze
+  FALSE_WORDS = %w[false no off].freeze
 
   def self.config
     @config ||= Configuration.new
@@ -28,99 +36,150 @@ module PM
 
   def self.configure
     yield config
+    config
   end
 
   # --- Parsing ---
 
-  # Parses a source through the full pipeline:
-  # strip HTML comments → extract YAML metadata → shell expansion (when shell: true).
+  # Parses a source through the full pipeline.
+  #
+  # When source is a Pathname, responds to :to_path, is a String ending in
+  # ".md", a Symbol, or a single word (e.g. "greeting"), it is treated as a
+  # file path. Symbols and single-word strings become "name.md" basenames.
+  # Relative paths are resolved against PM.config.prompts_dir. The file is
+  # read and `directory`, `name`, `created_at`, `modified_at` are added to
+  # the metadata.
   #
-  # When source is a Pathname, responds to :to_path, is a String ending
-  # in ".md", a Symbol, or a single word (e.g. "greeting"), it is treated
-  # as a file path. Symbols and single-word strings are converted to
-  # "name.md" basenames. The file is read and parsed, and `directory`,
-  # `name`, `created_at`, `modified_at` are added to metadata.
+  # Otherwise source is parsed directly as a string (see .parse_string).
   #
-  # Otherwise source is parsed directly as a string.
+  # Raises Errno::ENOENT when the file does not exist.
   def self.parse(source)
     source = "#{source}.md" if source.is_a?(Symbol) || single_word?(source)
-
-    if file_source?(source)
-      raw = source.respond_to?(:to_path) ? source.to_path : source
-      unless config.prompts_dir.empty?
-        raw = (Pathname.new(config.prompts_dir) + raw).to_s
-      end
-      path = File.expand_path(raw)
-      parsed = parse_string(File.read(path))
-
-      stat = File.stat(path)
-      metadata = build_metadata(
-        parsed.metadata.to_h.merge(
-          directory:   File.dirname(path),
-          name:        File.basename(path),
-          created_at:  stat.birthtime,
-          modified_at: stat.mtime
-        )
+    return parse_string(source) unless file_source?(source)
+
+    path   = resolve_path(source)
+    parsed = parse_string(File.read(path))
+    stat   = File.stat(path)
+
+    metadata = build_metadata(
+      parsed.metadata.to_h.merge(
+        directory:   File.dirname(path),
+        name:        File.basename(path),
+        created_at:  birthtime(stat),
+        modified_at: stat.mtime
       )
-      Parsed.new(metadata: metadata, content: parsed.content)
+    )
+    Parsed.new(metadata: metadata, content: parsed.content)
+  end
+
+  # Parses a string, never treating it as a file name.
+  #
+  # Raises PM::MetadataError when the front matter is not a YAML mapping, or
+  # when `shell`, `erb`, or `parameters` have values of the wrong type.
+  # YAML syntax errors raise Psych::SyntaxError.
+  def self.parse_string(string)
+    stripped = strip_comments(string)
+    match    = stripped.match(METADATA_REGEXP)
+
+    if match
+      metadata = build_metadata(load_front_matter(match[:metadata]))
+      content  = match[:content]
     else
-      parse_string(source)
+      metadata = build_metadata({})
+      content  = stripped
     end
+
+    content = expand_shell(content, erb_safe: metadata.erb?) if metadata.shell?
+
+    Parsed.new(metadata: metadata, content: content)
   end
 
-  # Returns true when source should be treated as a file path.
+  # Strips HTML comments from a string.
+  def self.strip_comments(string)
+    string.gsub(HTML_COMMENT_REGEXP, '')
+  end
+
+  # --- Internals ---
+
   def self.file_source?(source)
     source.respond_to?(:to_path) || (source.is_a?(String) && source.end_with?('.md'))
   end
   private_class_method :file_source?
 
-  # Returns true when source is a single word with no spaces,
-  # path separators, or file extension.
+  # True when source is a single word: no spaces, path separators, or extension.
   def self.single_word?(source)
     source.is_a?(String) && source.match?(/\A\w+\z/)
   end
   private_class_method :single_word?
 
-  # Parses a string through the full pipeline.
-  def self.parse_string(string)
-    stripped = strip_comments(string)
-    match = stripped.match(METADATA_REGEXP)
-
-    if match
-      metadata = build_metadata(YAML.safe_load(match[:metadata], permitted_classes: [Date, Time]))
-      content = match[:content]
-    else
-      metadata = build_metadata({})
-      content = stripped
-    end
+  def self.resolve_path(source)
+    raw = source.respond_to?(:to_path) ? source.to_path : source
+    raw = (Pathname.new(config.prompts_dir) + raw).to_s unless config.prompts_dir.empty?
+    File.expand_path(raw)
+  end
+  private_class_method :resolve_path
+
+  # File creation time, falling back to ctime where the platform or
+  # filesystem has no birthtime (several Linux filesystems, containers).
+  def self.birthtime(stat)
+    stat.birthtime
+  rescue NotImplementedError, NoMethodError
+    stat.ctime
+  end
+  private_class_method :birthtime
 
-    content = expand_shell(content) if metadata.shell?
+  def self.load_front_matter(yaml)
+    data = YAML.safe_load(yaml, permitted_classes: [Date, Time])
+    return {} if data.nil?
+    raise MetadataError, "Front matter must be a YAML mapping, got #{data.class}" unless data.is_a?(Hash)
 
-    Parsed.new(metadata: metadata, content: content)
+    data
   end
+  private_class_method :load_front_matter
 
-
-  # Builds a Metadata object with defaults for shell and erb.
+  # Builds Metadata with `shell` and `erb` resolved against the global config
+  # (the file wins unless the config is locked) and the `parameters` type checked.
   def self.build_metadata(hash)
-    defaults = { 'shell' => config.shell, 'erb' => config.erb }
-    Metadata.new(defaults.merge(hash.transform_keys(&:to_s)))
+    attrs = hash.transform_keys(&:to_s)
+
+    FLAG_KEYS.each do |key|
+      global = config.public_send(key)
+      value  = attrs[key]
+      attrs[key] = config.locked? || value.nil? ? global : coerce_flag(key, value)
+    end
+
+    params = attrs['parameters']
+    unless params.nil? || params.is_a?(Hash)
+      raise MetadataError, "parameters must be a mapping, got #{params.class}"
+    end
+
+    Metadata.new(attrs)
   end
   private_class_method :build_metadata
 
-  # Strips HTML comments from a string.
-  def self.strip_comments(string)
-    string.gsub(HTML_COMMENT_REGEXP, '')
+  def self.coerce_flag(key, value)
+    return value if value.equal?(true) || value.equal?(false)
+
+    word = value.to_s.strip.downcase
+    return true  if TRUE_WORDS.include?(word)
+    return false if FALSE_WORDS.include?(word)
+
+    raise MetadataError, "#{key} must be true or false, got #{value.inspect}"
   end
+  private_class_method :coerce_flag
 end
 
-require_relative 'pm/configuration'
 require_relative 'pm/version'
+require_relative 'pm/errors'
+require_relative 'pm/configuration'
 require_relative 'pm/metadata'
+require_relative 'pm/render_scope'
+require_relative 'pm/renderer'
 require_relative 'pm/parsed'
+require_relative 'pm/shell'
 require_relative 'pm/directives'
 require_relative 'pm/directive'
 require_relative 'pm/core_directives'
-require_relative 'pm/shell'
 
 # Register built-in directives from PM::CoreDirectives
 PM::Directive.register_all

data/lib/prompt_manager.rb

@@ -1,3 +1,9 @@
+# frozen_string_literal: true
+
+# Entry point for `require 'prompt_manager'` (the gem name, which Bundler
+# auto-requires). The library lives in the PM namespace; PromptManager is a
+# namespace alias only. The 0.x PromptManager::Prompt / Storage API was
+# removed in 1.0.0 and is not provided here.
 require_relative 'pm'
 
 PromptManager = PM

metadata

@@ -1,142 +1,40 @@
 --- !ruby/object:Gem::Specification
 name: prompt_manager
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: ostruct
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: amazing_print
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: debug_me
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+dependencies: []
 description: |
-  PM (PromptManager) parses YAML metadata from markdown strings or files.
-  It expands shell references, extracts metadata and content, and renders
-  ERB templates on demand.
+  PM (PromptManager) parses YAML front matter from markdown strings or files.
+  It expands shell references, extracts metadata and content, composes prompts
+  from other files with include/insert directives, and renders ERB on demand.
 email:
 - dvanhoozer@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".envrc"
-- ".irbrc"
 - CHANGELOG.md
-- COMMITS.md
 - LICENSE
 - README.md
-- Rakefile
-- docs/api/configuration.md
-- docs/api/constants.md
-- docs/api/index.md
-- docs/api/metadata.md
-- docs/api/parsed.md
-- docs/api/pm-module.md
-- docs/api/render-context.md
-- docs/architecture/design-decisions.md
-- docs/architecture/index.md
-- docs/architecture/processing-pipeline.md
-- docs/assets/css/custom.css
-- docs/assets/images/prompt_manager.gif
-- docs/assets/images/prompt_manager.mp4
-- docs/examples/ai-agent-prompts.md
-- docs/examples/code-review-prompt.md
-- docs/examples/index.md
-- docs/examples/multi-file-composition.md
-- docs/getting-started/configuration.md
-- docs/getting-started/index.md
-- docs/getting-started/installation.md
-- docs/getting-started/quick-start.md
-- docs/guides/comment-stripping.md
-- docs/guides/custom-directives.md
-- docs/guides/erb-rendering.md
-- docs/guides/includes.md
-- docs/guides/index.md
-- docs/guides/parameters.md
-- docs/guides/parsing.md
-- docs/guides/shell-expansion.md
-- docs/index.md
 - lib/pm.rb
 - lib/pm/configuration.rb
 - lib/pm/core_directives.rb
 - lib/pm/directive.rb
 - lib/pm/directives.rb
+- lib/pm/errors.rb
 - lib/pm/metadata.rb
 - lib/pm/parsed.rb
+- lib/pm/render_scope.rb
+- lib/pm/renderer.rb
 - lib/pm/shell.rb
 - lib/pm/version.rb
 - lib/prompt_manager.rb
-- mkdocs.yml
 homepage: https://github.com/MadBomber/prompt_manager
 licenses:
 - MIT
@@ -144,7 +42,9 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/MadBomber/prompt_manager
   source_code_uri: https://github.com/MadBomber/prompt_manager
-  changelog_uri: https://github.com/MadBomber/prompt_manager
+  changelog_uri: https://github.com/MadBomber/prompt_manager/blob/main/CHANGELOG.md
+  documentation_uri: https://madbomber.github.io/prompt_manager
+  bug_tracker_uri: https://github.com/MadBomber/prompt_manager/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -152,14 +52,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 4.0.9
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.23
 specification_version: 4
 summary: Parse YAML metadata from markdown prompts with shell expansion and ERB rendering
 test_files: []

data/.envrc

@@ -1,3 +0,0 @@
-# prompt_manager/.envrc
-
-export RR=`pwd`

data/.irbrc

@@ -1,14 +0,0 @@
-require_relative 'lib/prompt_manager'
-require_relative 'lib/prompt_manager/storage/file_system_adapter'
-
-HERE = Pathname.new __dir__
-
-PromptManager::Storage::FileSystemAdapter.config do |config|
-  config.prompts_dir        = HERE + 'examples/prompts_dir'
-  # config.search_proc      = nil     # default
-  # config.prompt_extension = '.txt'  # default
-  # config.parms+_extension = '.json' # default
-end
-
-PromptManager::Prompt.storage_adapter = PromptManager::Storage::FileSystemAdapter.new
-